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