46 lines
2 KiB
Markdown
46 lines
2 KiB
Markdown
|
# SCOPE.md — llm-connect
|
||
|
|
|
||
|
|
## Purpose
|
||
|
|
|
||
|
|
`llm-connect` is a **multi-provider LLM client library for Python**.
|
||
|
|
It provides a unified adapter interface over OpenAI, Gemini, OpenRouter,
|
||
|
|
and the Claude Code CLI, with embedding support, token estimation, and a
|
||
|
|
TOML-based configuration chain.
|
||
|
|
|
||
|
|
Extracted from [markitect](https://github.com/worsch/markitect).
|
||
|
|
The `markitect.llm` module remains a re-export shim pointing here.
|
||
|
|
|
||
|
|
## This repo owns
|
||
|
|
|
||
|
|
- `LLMAdapter` ABC and `RunConfig` / `LLMResponse` data models (Core)
|
||
|
|
- All concrete provider adapters: `OpenAIAdapter`, `GeminiAdapter`,
|
||
|
|
`OpenRouterAdapter`, `ClaudeCodeAdapter` (Functional)
|
||
|
|
- Embedding adapters: `EmbeddingAdapter` ABC, `OpenAICompatibleEmbeddingAdapter`,
|
||
|
|
`EmbeddingCache`, `create_embedding_adapter` factory (Functional)
|
||
|
|
- TOML-based config resolution (`toml_config.py`, `config.py`) (Configuration)
|
||
|
|
- Shared HTTP utility (`_http.py`), token estimator (`_token_estimator.py`),
|
||
|
|
cosine similarity utilities (`similarity.py`)
|
||
|
|
- The full `LLMError` exception hierarchy
|
||
|
|
|
||
|
|
## This repo does NOT own
|
||
|
|
|
||
|
|
- Consumer application logic — that lives in `markitect`, `inter-hub`, etc.
|
||
|
|
- API key management infrastructure — keys are resolved from env vars or
|
||
|
|
plaintext key files; secret storage belongs in the calling environment
|
||
|
|
- Model routing decisions specific to a consumer — `RoutingPolicy` (WP-0003)
|
||
|
|
provides primitives; policy configuration belongs in the consumer
|
||
|
|
- The Claude Code CLI binary itself — `ClaudeCodeAdapter` shells out to `claude`
|
||
|
|
|
||
|
|
## Consumers (as of 2026-04-01)
|
||
|
|
|
||
|
|
| Consumer | How it uses llm-connect |
|
||
|
|
|----------|------------------------|
|
||
|
|
| `markitect` | Re-exports via `markitect.llm` shim; drives document generation |
|
||
|
|
| `inter-hub` (IHF) | Subprocess bridge (`scripts/llm_bridge.py` + `AgentBridge.hs`) for multi-agent federation |
|
||
|
|
|
||
|
|
## Versioning
|
||
|
|
|
||
|
|
- Current version: **0.1.0** (pre-release; API not yet stable)
|
||
|
|
- Core layer (`LLMAdapter`, `RunConfig`, `LLMResponse`) will be stabilised at **v1.0.0**
|
||
|
|
- Breaking Core changes require a major version bump
|