Files

Bernd Worsch d71f4114d1 feat: WP-0001 foundation + WP-0002 core extensions

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>

2026-04-01 22:24:14 +00:00

4.2 KiB

Raw Blame History

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
`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)

4.2 KiB Raw Blame History