# Library Registry

## Summary

The Aetos ecosystem provides internal libraries for the shared concerns of
every application. **Use them.** Writing a private copy of any capability below
is a defect.

Each library also exposes its own documentation as an MCP server. An AI agent
can read a library's full API by connecting to its MCP and reading
`doc://index`, `doc://nav`, and `doc://modules/{module}`.

---

## Catalog

| Library | Import | Purpose | Use instead of | MCP |
|---|---|---|---|---|
| DAG Pipe | `dagpipe` | Deterministic state-transformation DAG engine | hand-rolled orchestration/topological ordering | `:8006` |
| Hexa | `hexa` | Declarative DI / composition-root tooling | manual wiring, hand-written factories | `:8008` |
| Mongo Ops | `mongo_ops` | Async MongoDB repositories, cache, populate, transactions | raw Motor CRUD and connection lifecycle | `:8007` |
| Omniread | `omniread` | Format-agnostic fetch + parse (HTML, PDF, CSV, XLSX) | custom scrapers/parsers | `:8003` |
| OpenAPI First | `openapi_first` | Spec-first FastAPI bootstrap, client, codegen | decorator routers and hand-written clients | `:8004` |
| Mail Intake | `mail_intake` | Provider-agnostic read-only email ingestion | Gmail OAuth + MIME parsing | `:8002` |
| Py JWT | `jwtlib` | JWT auth primitives (register/login/introspect) | password hashing + token code | `:8005` |
| Doc Forge | `docforge` | Docstring compiler → MkDocs + MCP docs | custom doc generators | `:8001` |
| Auth Server | *(service)* | Central identity service (register/login/me/introspect) | building auth endpoints yourself | *(deferred)* |

## How to choose

| You need to… | Use |
|---|---|
| persist and query documents | Mongo Ops |
| compose dependencies | Hexa |
| run a multi-step transformation | DAG Pipe |
| read/parse an arbitrary input format | Omniread |
| expose a contract-first HTTP API | OpenAPI First |
| ingest email | Mail Intake |
| authenticate users / verify tokens | Py JWT (+ Auth Server) |
| generate documentation | Doc Forge |

## Discovery

A single **standards MCP** exposes `find_library(capability)`, which returns the
matching library, its import name, its "use instead of" guidance, and its MCP
endpoint. Query it before writing any infrastructure.

## Notes

- **Hexa** is a full library with its own MCP server on `:8008`: read
  `doc://index`, `doc://nav`, and `doc://modules/{module}` (e.g.
  `doc://modules/hexa.container`) to discover the DI surface — `build(cls, *,
  instances, config)` and the `PortNode` model.
- **Auth Server** is deferred: it has no `pyproject.toml`/importable package and
  no MCP bundle. Do not reach for it yet; `py-jwt` covers token primitives.
- Library MCP servers expose **documentation resources** (not executable tools):
  they tell an agent the available API surface so it does not invent code.