generated from coulomb/repo-seed
Bernd Worsch
d71f4114d1
WP-0001 — Foundation & GAAF Baseline - SCOPE.md, ARCHITECTURE-LAYERS.md, contracts/ tree - .claude/rules/ stubs filled (architecture, stack, boundary) - 57 tests (pytest), pyproject.toml with ruff+mypy, CI workflow WP-0002 — Core Extensions (FR-4 + FR-3) - FR-4: BudgetTracker (thread-safe) + LLMBudgetExceededError + optional RunConfig.budget_tracker + enforcement in all adapters - FR-3: async_execute_prompt on LLMAdapter ABC (asyncio.to_thread fallback) + native asyncio.create_subprocess_exec in ClaudeCodeAdapter 81 tests passing. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
46 lines
2.0 KiB
Markdown
46 lines
2.0 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
|