generated from coulomb/repo-seed
98 lines
4.4 KiB
Markdown
98 lines
4.4 KiB
Markdown
# ARCHITECTURE-LAYERS.md
|
|
|
|
**Framework:** GAAF-2026
|
|
**Last reviewed:** 2026-04-01
|
|
**Repository purpose:** Multi-provider LLM client library — unified adapter interface for Python
|
|
**Next review:** 2026-07-01
|
|
|
|
---
|
|
|
|
## Layer Map
|
|
|
|
### Core (high rigidity — frozen after v1)
|
|
|
|
Domain-agnostic primitives. Must not change without a major version bump once stable.
|
|
|
|
| Module | Contents |
|
|
|--------|----------|
|
|
| `adapter.py` | `LLMAdapter` ABC (`execute_prompt`, `validate_config`); `MockLLMAdapter`; `ErrorLLMAdapter` |
|
|
| `models.py` | `RunConfig`, `LLMResponse` dataclasses |
|
|
| `exceptions.py` | `LLMError` → `LLMConfigurationError`, `LLMAPIError`, `LLMRateLimitError`, `LLMTimeoutError`, `LLMSubprocessError` |
|
|
|
|
**Contract:** `contracts/core/llm-adapter.md`
|
|
|
|
### Functional (medium rigidity — evolvable, versioned)
|
|
|
|
Value-realization modules. Each adapter is independently shippable.
|
|
Maturity states: **Experimental → Beta → Stable → Deprecated**
|
|
|
|
| Module | Contents | Maturity |
|
|
|--------|----------|----------|
|
|
| `openai.py` | `OpenAIAdapter` — OpenAI chat completions | Beta |
|
|
| `gemini.py` | `GeminiAdapter` — Google Generative Language API | Beta |
|
|
| `openrouter.py` | `OpenRouterAdapter` — OpenAI-compatible multi-model routing | Beta |
|
|
| `claude_code.py` | `ClaudeCodeAdapter` — `claude --print` subprocess | Beta |
|
|
| `_payload.py` | Shared adapter payload translation for `RunConfig.model_params` | Beta |
|
|
| `_diagnostics.py` | Opt-in per-call diagnostics capture for server debug and audit modes | Beta |
|
|
| `replay.py` | Audit replay parser CLI (`python -m llm_connect.replay`) | Beta |
|
|
| `embedding_adapter.py` | `EmbeddingAdapter` ABC | Beta |
|
|
| `embedding_openai.py` | `OpenAICompatibleEmbeddingAdapter` | Beta |
|
|
| `embedding_cache.py` | `EmbeddingCache` — disk-backed embedding cache | Beta |
|
|
| `embedding_factory.py` | `create_embedding_adapter()` factory | Beta |
|
|
| `factory.py` | `create_adapter()` factory — lazy provider registration | Beta |
|
|
| `_token_estimator.py` | Rough token count estimation (word-based) | Beta |
|
|
| `similarity.py` | `cosine_similarity`, `similarity_matrix`, `find_similar_pairs` | Beta |
|
|
|
|
**Planned additions (WP-0003):** `RoutingPolicy`, `server.py`
|
|
**Contracts:** `contracts/functional/`
|
|
|
|
### Configuration (very low rigidity — user-controlled declarative state)
|
|
|
|
| Module | Contents |
|
|
|--------|----------|
|
|
| `toml_config.py` | `resolve_llm()` — 7-level TOML priority chain; `ResolvedLLM`; `LLMLayer` |
|
|
| `config.py` | `LLMConfig` dataclass; `resolve_api_key()`; `find_project_root()`; `load_config()` |
|
|
| `_http.py` | Shared HTTP POST utility (used by Functional adapters) |
|
|
|
|
**Contracts:** `contracts/config/`
|
|
|
|
---
|
|
|
|
## Dependency Rule
|
|
|
|
```
|
|
Core ← Functional ← Configuration
|
|
```
|
|
|
|
Upward dependencies (Configuration → Functional, Functional → Core) are **prohibited**.
|
|
`_http.py` sits in the Configuration layer but is consumed only by Functional adapters — acceptable as a shared utility with no upward reach.
|
|
|
|
---
|
|
|
|
## Decisions Log
|
|
|
|
| Date | Decision | Rationale |
|
|
|------|----------|-----------|
|
|
| 2026-04-01 | FR-3 async: default executor fallback on ABC rather than abstract method | Non-breaking; existing adapters remain valid; native async opt-in per adapter |
|
|
| 2026-04-01 | FR-4 BudgetTracker: optional field on RunConfig, not a separate context object | Keeps RunConfig as single call config; avoids thread-local / contextvar complexity |
|
|
| 2026-04-01 | FR-1 HTTP server: optional dep `[server]`, not runtime dep | Keeps base install lightweight; most consumers call the library directly |
|
|
|
|
---
|
|
|
|
## GAAF-2026 Scorecard (initial baseline — 2026-04-01)
|
|
|
|
> Scoring: 0 = absent / harmful · 5 = excellent
|
|
|
|
| Dimension | Score | Notes |
|
|
|-----------|-------|-------|
|
|
| **Core** | 2.5 | ABC and models well-defined; no formal contracts, no tests, no invariant docs yet |
|
|
| **Functional** | 2.5 | Adapters isolated and independently usable; no maturity labels enforced, no tests |
|
|
| **Customization** | n/a | Not applicable (library, not SaaS) |
|
|
| **Configuration** | 2.0 | TOML chain works; no schema validation; `markitect` name coupling in toml_config defaults |
|
|
| **Extensions** | n/a | Not applicable yet (RoutingPolicy + server in WP-0003) |
|
|
| **Cross-layer** | 2.0 | Dependency direction correct; no CI fitness functions; no import graph checks |
|
|
| **Weighted total** | ~2.3 | Usable but vulnerable — WP-0001 targets ≥ 3.5 |
|
|
|
|
**Target after WP-0001:** ≥ 3.5 (Strong)
|
|
**Target after WP-0002 + WP-0003:** ≥ 4.0 (Strong / Exemplary)
|