llm-connect/ARCHITECTURE-LAYERS.md

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)