|
| 1 | +# Lib-Bot |
| 2 | + |
| 3 | +Lib-Bot is a harness-neutral agentic system for interacting with University of |
| 4 | +Chicago Library systems. It targets Claude Code first but is structured so any |
| 5 | +agent harness can drive the same skills. |
| 6 | + |
| 7 | +The canonical skills live under `skills/`. Harness-specific discovery |
| 8 | +directories such as `.claude/skills/` (and, later, `.agents/skills/`) are |
| 9 | +adapters — usually symlinks — back to the canonical skill directories. No skill |
| 10 | +content is duplicated; to support a new harness, add its discovery directory and |
| 11 | +symlink the same canonical skills in. |
| 12 | + |
| 13 | +## Skills |
| 14 | + |
| 15 | +- **`catalog-search`** — Search the UChicago Library catalog (VuFind) and enrich |
| 16 | + results with data the catalog can't surface. Every search returns normalized |
| 17 | + records (with a `searchUrl` to the full results page in the catalog UI) plus: |
| 18 | + WikiData author context (inline, every result); an Internet Archive "full text |
| 19 | + available" badge with an on-demand pull for public-domain titles; a verify-first |
| 20 | + full-text **discovery** path (Project Gutenberg + IA library scans) for works |
| 21 | + the badge misses; opt-in **PubMed** topical evidence for biomedical subjects; |
| 22 | + and **HathiTrust/HTRC** content analysis that fingerprints a book's themes and |
| 23 | + named entities even when it's in-copyright and unreadable. Plain requests to |
| 24 | + *search the catalog, find a book, look up holdings, narrow by |
| 25 | + format/year/language, learn about an item's author, read/summarize a |
| 26 | + public-domain title, find where a work's full text is freely available, see |
| 27 | + recent evidence on a health topic, or learn what an in-copyright book is about* |
| 28 | + route here. Sources are high-trust only (catalog, WikiData, Gutenberg, |
| 29 | + OpenLibrary, IA institutional scans, HathiTrust, PubMed) — never community |
| 30 | + uploads. Does **not** do live FOLIO checkout availability, and never claims |
| 31 | + full text it can't actually deliver. |
| 32 | + |
| 33 | +## Conventions |
| 34 | + |
| 35 | +- **Skill instructions are harness-agnostic.** They describe fan-out with the |
| 36 | + abstract verb **"spawn a sub-agent"** rather than a Claude-Code-specific tool. |
| 37 | + Each harness adapter maps "spawn" to its own primitive (Claude Code → |
| 38 | + `Agent(...)`, etc.) and a capability class to a concrete model. |
| 39 | +- **Scripts run with `${LIBBOT_PYTHON:-.venv/bin/python}`** from the repo root — |
| 40 | + the project venv by default, or whatever `LIBBOT_PYTHON` points at. Set the venv |
| 41 | + up once with `python3 -m venv .venv && .venv/bin/pip install .[all]` |
| 42 | + (dependencies are per-tool extras in `pyproject.toml`; the core skill is pure |
| 43 | + stdlib). Each script adds its own directory to the path, so the canonical |
| 44 | + `skills/<name>/scripts/...` paths work as-is. |
| 45 | +- **Configuration is data, not code.** Knobs live in an optional, gitignored |
| 46 | + repo-root `config.json` — **per tool**, nested under the tool's key |
| 47 | + (`{"catalog-search": {...}}`) — or `LIBBOT_*` env vars; |
| 48 | + secrets (API keys) never go inline or in version control. |
| 49 | +- **Enrichment must be honest and fail-soft.** Only surface enrichment that was |
| 50 | + actually retrieved; a slow or missing source drops its annotation without |
| 51 | + breaking the underlying search. |
| 52 | +- **Lint before committing.** `pip install .[dev]` pulls flake8, black, and |
| 53 | + isort (config in `.flake8` and `pyproject.toml`); CI runs the same checks in |
| 54 | + `.github/workflows/lint.yml`. Run `black . && isort . && flake8 .` locally |
| 55 | + before opening a PR. |
| 56 | + |
| 57 | +## Layout |
| 58 | + |
| 59 | +``` |
| 60 | +skills/<name>/ |
| 61 | + SKILL.md # canonical skill instructions (harness-neutral) |
| 62 | + scripts/ # run with ${LIBBOT_PYTHON:-.venv/bin/python} |
| 63 | +.claude/skills/<name> -> ../../skills/<name> # Claude Code discovery (symlink) |
| 64 | +config.example.json # copy to repo-root config.json to override defaults |
| 65 | +pyproject.toml # deps as per-tool extras (.[all], .[<tool>]) |
| 66 | +DESIGN.md # architecture + integration facts |
| 67 | +``` |
| 68 | + |
| 69 | +See `DESIGN.md` for the full architecture (pipeline, normalized record shape, |
| 70 | +enricher contract, source roster, integration facts) and the README for current |
| 71 | +build status. |
0 commit comments