mark-watson/loving-common-lisp/cl-book-apis

Mark's Common Lisp Utilities APIs

Knowledge of public APIs and how to run code for these Common Lisp libraries by Mark Watson.

Quicklisp Loading

All libraries are loaded via Quicklisp after copying to ~/quicklisp/local-projects/:

(ql:quickload :package-name)

entities

Load: (ql:quickload :entities) Deps: myutils Data files: Loads linguistic_data/names.{cities,companies,countries,people,products,universities} at compile/load time.

Exported API

• (entities:entity) — Struct with slots: cities, companies, countries, people, products, universities
• (entities:text->entities words) — Main NER entry point. Accepts a string or vector of word strings. Returns an entity struct with matched names. Checks 1/2/3-word phrases.
• (entities:entities-cities eo) / entities-companies / entities-countries / entities-people / entities-products / entities-universities — Accessor slots on entity struct.

Example

(entities:text->entities "President Bush went to San Diego to meet Ms Jones at Google")

gemini

Load: (ql:quickload :gemini) Deps: uiop, cl-json, alexandria Env var: GOOGLE_API_KEY Default model: gemini-3-flash-preview

Exported API

• (gemini:generate prompt &optional model-id) — Generate text from a prompt. Returns text string.
• (gemini:count-tokens prompt &optional model-id) — Count tokens for a prompt. Returns integer.
• (gemini:generate-with-search prompt &optional model-id) — Generate with Google Search grounding. Returns text string.
• (gemini:generate-with-search-and-citations prompt &optional model-id) — Returns (values text citations) where citations is a list of (title . url) cons pairs.
• (gemini:make-function-declaration name description parameters &optional required-params) — Build a function declaration hash-table for tool use. Parameters is list of (name type description) triples.
• (gemini:generate-with-tools prompt function-declarations &key model-id google-search-p) — Turn 1: send prompt with tools. Returns (values text function-calls model-content-ht). Function-calls is list of plists (:NAME :ID :ARGS).
• (gemini:continue-with-function-responses original-prompt model-content-ht function-responses function-declarations &key model-id google-search-p) — Turn 2+: provide function results. Function-responses is list of plists (:NAME :ID :RESPONSE). Returns final text.

Examples

(gemini:generate "Write a short poem about coding.") (gemini:generate-with-search "What sci-fi movies are playing at Harkins 16 in Flagstaff today?") (multiple-value-bind (response sources) (gemini:generate-with-search-and-citations "Who won the Super Bowl in 2024?") (format t "Answer: ~a~%Sources: ~a~%" response sources))

kbnlp

Load: (ql:quickload :kbnlp) Deps: myutils, fasttag, entity-uris Data files: Loads extensive linguistic data at compile/load time (names, places, companies, products, stop words, category data).

Exported API

• (kbnlp:make-text-object) — Constructor for text struct.
• (kbnlp:sumarize text-object) — Summarize a text object (note: spelling with one 'm').
• (kbnlp:text) — Struct with slots: url, title, summary, category-tags, key-words, key-phrases, human-names, place-names, company-names, text, tags.
• (kbnlp:replace-all string part replacement &key test) — Replace all occurrences of part with replacement in string.

Internal helpers (not exported but useful to know)

• find-names — Detect human names in word vector using POS tags + name hash tables
• find-places — Detect place names in word vector
• find-companies — Detect company names in word vector
• find-names-places — Wrapper that finds both names and places in a text object
• get-word-list-category — Classify text into categories using word scoring

knowledge-base-navigator

Load: (ql:quickload :knowledge-base-navigator) Deps: cl-json, uiop, alexandria Env var: GEMINI_API_KEY Model: gemini-3-flash-preview

Exported API

• (knowledge-base-navigator:kbn-ui) — Interactive REPL loop. Enter entity names or descriptive sentences; Gemini extracts entities, shows numbered list; user picks numbers for detailed info.
• (knowledge-base-navigator:get-gemini-chat-completion user-prompt) — Low-level: send a prompt to Gemini, return text response string.

Example

(knowledge-base-navigator:kbn-ui) ;; Then interactively: "Bill Gates Microsoft Seattle"

lightpanda

Load: (ql:quickload :lightpanda) Deps: cl-json Binary required: lightpanda headless browser on PATH (or set *lightpanda-binary*)

Exported API

• lightpanda:*lightpanda-binary* — Path to lightpanda binary (default: "lightpanda").
• (lightpanda:fetch-url url &key log-level obey-robots dump) — Fetch URL via lightpanda headless browser. :dump controls output format: "html" (default), "markdown", "semantic_tree", "semantic_tree_text". Returns JS-rendered content string.
• (lightpanda:fetch-and-extract-links url) — Fetch URL and return list of href link strings.
• (lightpanda:demo-fetch url) — Fetch URL, print HTML snippet and discovered links.

Examples

(lightpanda:fetch-url "https://markwatson.com/") (lightpanda:fetch-url "https://markwatson.com/" :dump "markdown") (lightpanda:fetch-and-extract-links "https://markwatson.com/")

ollama

Load: (ql:quickload :ollama) Deps: uiop, cl-json Server: Requires Ollama running at http://localhost:11434/api/chat Default model: mistral:v0.3 / tool model: qwen3:1.7b

Exported API

• (ollama:completions starter-text) — Simple completion. Returns text string.
• (ollama:completions-with-tools starter-text &optional functions) — Completion with tool/function calling. functions is list of registered function name strings. Returns text or function call result.
• (ollama:summarize some-text) — Summarize text via completions.
• (ollama:answer-question some-text) — Answer a question via completions.
• ollama:*model-name* — Default model name (mistral:v0.3)
• ollama:*tool-model-name* — Tool-calling model name (qwen3:1.7b)
• ollama:*model-host* — API host URL

Tool registration (internal but key)

• (ollama::register-tool-function name description parameters handler) — Register a CL function for LLM tool calling.
• Pre-registered: get_weather, calculate

Cloud search agent (requires OLLAMA_API_KEY)

• (ollama::cloud-search-agent prompt) — Agent loop using Ollama Cloud with web_search and web_fetch tools. Returns final answer string.
• Model: gpt-oss:120b-cloud

Examples

(ollama:completions "Complete the following text: The President went to") (ollama:summarize "Long text to summarize...") (ollama:answer-question "Where were the 1992 Olympics held?") (ollama::completions-with-tools "What's the weather in NY?" '("get_weather"))

ollama_images

Not an ASDF system. Load standalone: (load "ollama_images/describe-image.lisp") Deps: cl-base64, cl-json, uiop (quickloaded internally) Server: Requires Ollama running with a vision model Default model: qwen3.5:0.8b Env vars: OLLAMA_MODEL, OLLAMA_HOST (optional overrides)

Package: describe-image

• (describe-image:image-to-text image-paths prompt &key model host) — Send one or more images to Ollama vision model with a text prompt. image-paths can be a single string or list of strings. Returns text string.
• (describe-image:describe-image-simple image-path) — Convenience: describe a single image with default prompt "What is in this image?".
• describe-image:*model-name* — Default vision model.
• describe-image:*ollama-host* — Ollama API endpoint.

Examples

(describe-image:image-to-text "ticket.png" "Print out the plain text in this image") (describe-image:image-to-text '("a.png" "b.png") "Compare these two images.") (describe-image:describe-image-simple "photo.jpg")

sparql

Load: (ql:quickload :sparql) Deps: uiop, drakma, cl-json, myutils

Exported API

• (sparql:dbpedia query) — Query DBpedia SPARQL endpoint. Returns list of bindings ((var-name . value) ...).
• (sparql:wikidata query) — Query Wikidata SPARQL endpoint. Returns list of bindings.
• (sparql:fuseki query &key host port suffix) — Query Fuseki SPARQL endpoint. Default: http://127.0.0.1:3030/news/sparql.
• (sparql:agraph query &key host port suffix) — Query AllegroGraph SPARQL endpoint with basic auth.
• (sparql:stardog query &key host port suffix) — Query Stardog SPARQL endpoint with basic auth.
• (sparql:ask-dbpedia query) — Boolean ASK query to DBpedia. Returns T or NIL.
• (sparql:sparql-manual) — Print example SPARQL queries.

Examples

(sparql:dbpedia "select ?s ?p { ?s ?p \"Steve Jobs\"@en }") (sparql:wikidata "select ?s ?p { ?s ?p \"Bill Gates\"@en }") (sparql:ask-dbpedia "ASK { ?s ?p \"Steve Jobs\"@en }") (sparql:fuseki "select ?s ?p ?o { ?s ?p ?o }" :port 3030)

General Notes

• All LLM API libraries use curl via uiop:run-program for HTTP requests (no HTTP client library). For a single uniform LLM interface use the litelm library in src/litelm ((asdf:load-system :litelm)), which routes "provider/model" strings to OpenAI, Gemini, Fireworks AI, DeepSeek, or a local Ollama server and also provides embeddings.
• Environment variables must be set before use: GOOGLE_API_KEY, GEMINI_API_KEY, OPENAI_KEY, FIREWORKS_API_KEY, DEEPSEEK_API_KEY, OLLAMA_API_KEY (cloud only).
• The myutils package provides shared utilities like tokenize-string and replace-all used by several libraries.
• Data-loading libraries (entities, kbnlp) read linguistic data files at load time; *base-pathname* is resolved at compile time relative to source file location.