generated from coulomb/repo-seed
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>
This commit is contained in:
36
workplans/llm-connect-WP-0001-foundation-gaaf-baseline.md
Normal file
36
workplans/llm-connect-WP-0001-foundation-gaaf-baseline.md
Normal file
@@ -0,0 +1,36 @@
|
||||
# LLM-WP-0001 — Foundation & GAAF Baseline
|
||||
|
||||
**status:** active
|
||||
**owner:** llm-connect
|
||||
**repo:** llm-connect
|
||||
**created:** 2026-04-01
|
||||
|
||||
## Purpose
|
||||
|
||||
Establish the structural foundation required before any Core modifications.
|
||||
Covers repo orientation files, GAAF-2026 compliance artifacts, test suite, CI,
|
||||
and state-hub housekeeping.
|
||||
|
||||
## Tasks
|
||||
|
||||
| ID | Title | Priority | Status |
|
||||
|-----|-------|----------|--------|
|
||||
| T01 | Create `SCOPE.md` | high | done |
|
||||
| T02 | Fill `.claude/rules/` stubs: `architecture.md`, `stack-and-commands.md`, `repo-boundary.md` | high | done |
|
||||
| T03 | Create `ARCHITECTURE-LAYERS.md` with layer map, scorecard stub, next-review date | high | done |
|
||||
| T04 | Create `/contracts/` tree (`core/`, `functional/`, `config/`) | high | done |
|
||||
| T05 | Core contract doc: `LLMAdapter` interface invariants, `RunConfig`/`LLMResponse` field contracts | high | done |
|
||||
| T06 | Functional contract stubs for all 4 adapters + embedding adapters (maturity: Beta) | medium | done |
|
||||
| T07 | Create `tests/` with `conftest.py`, wire pytest in `pyproject.toml` | high | done |
|
||||
| T08 | Unit tests: `RunConfig`, `LLMResponse`, `MockLLMAdapter`, full exception hierarchy | high | done |
|
||||
| T09 | Unit tests: `create_adapter` (all providers + unknown provider error), `create_embedding_adapter` | high | done |
|
||||
| T10 | Add `ruff`, `mypy` to dev deps in `pyproject.toml` | medium | done |
|
||||
| T11 | CI workflow: pytest + ruff + mypy | medium | done |
|
||||
| T12 | State hub: register this host path, SBOM refresh | low | done |
|
||||
|
||||
## Exit criteria
|
||||
|
||||
- `ARCHITECTURE-LAYERS.md` and `/contracts/core/` exist and describe the current Core surface
|
||||
- pytest passes with coverage of Core and factory
|
||||
- ruff + mypy clean
|
||||
- CI green on push
|
||||
57
workplans/llm-connect-WP-0002-core-extensions.md
Normal file
57
workplans/llm-connect-WP-0002-core-extensions.md
Normal file
@@ -0,0 +1,57 @@
|
||||
# LLM-WP-0002 — Core Extensions (FR-4 + FR-3)
|
||||
|
||||
**status:** active
|
||||
**owner:** llm-connect
|
||||
**repo:** llm-connect
|
||||
**created:** 2026-04-01
|
||||
**depends-on:** LLM-WP-0001 (contracts and tests must exist before Core is modified)
|
||||
|
||||
## Purpose
|
||||
|
||||
Implement the two IHF feature requests that touch the Core layer.
|
||||
FR-4 (BudgetTracker) is additive and non-breaking. FR-3 (async) extends
|
||||
the Core ABC with a default executor fallback — non-breaking, overridable
|
||||
per adapter for native async.
|
||||
|
||||
Origin: IHUB-WP-0012 Phase 11 — Advanced AI Federation (completed 2026-04-01).
|
||||
|
||||
## GAAF notes
|
||||
|
||||
Both changes are Core-layer modifications under GAAF-2026:
|
||||
- FR-4: new primitive (`BudgetTracker`) + new exception (`LLMBudgetExceededError`)
|
||||
added as optional `RunConfig` field — additive, non-breaking.
|
||||
- FR-3: `async_execute_prompt` added to `LLMAdapter` ABC with a default
|
||||
`asyncio.get_event_loop().run_in_executor(None, ...)` fallback so existing
|
||||
adapters remain valid; native async overrides are provided per adapter.
|
||||
|
||||
Core contract doc (from WP-0001 T05) must be updated after each change.
|
||||
|
||||
## Tasks
|
||||
|
||||
### FR-4 — BudgetTracker
|
||||
|
||||
| ID | Title | Priority | Status |
|
||||
|-----|-------|----------|--------|
|
||||
| T01 | `BudgetTracker` dataclass: `total`, `spent`, `remaining()`, thread-safe increment | high | todo |
|
||||
| T02 | `LLMBudgetExceededError(LLMError)` in `exceptions.py` | high | todo |
|
||||
| T03 | Optional `budget_tracker: BudgetTracker \| None` field on `RunConfig` | high | todo |
|
||||
| T04 | Enforcement: each adapter checks/updates tracker around call; raises on exceeded | high | todo |
|
||||
| T05 | Update Core contract doc | medium | todo |
|
||||
| T06 | Tests: single call, delegation chain (A→B→C shared tracker), exceeded error, multi-adapter | high | todo |
|
||||
|
||||
### FR-3 — async_execute_prompt
|
||||
|
||||
| ID | Title | Priority | Status |
|
||||
|-----|-------|----------|--------|
|
||||
| T07 | Add `async_execute_prompt` to `LLMAdapter` ABC with default executor fallback | high | todo |
|
||||
| T08 | Native async override in `OpenAIAdapter`, `GeminiAdapter`, `OpenRouterAdapter` | high | todo |
|
||||
| T09 | Native async for `ClaudeCodeAdapter` via `asyncio.create_subprocess_exec` | high | todo |
|
||||
| T10 | Update Core contract doc | medium | todo |
|
||||
| T11 | Tests: `asyncio.gather` over N adapters, timeout propagation, budget interaction | high | todo |
|
||||
|
||||
## Exit criteria
|
||||
|
||||
- `BudgetTracker` enforces caps across a delegation chain of 3 adapters in tests
|
||||
- `asyncio.gather` over 4 mock adapters completes without errors
|
||||
- All existing tests still pass (non-breaking validation)
|
||||
- Core contract doc reflects both additions
|
||||
51
workplans/llm-connect-WP-0003-functional-extensions.md
Normal file
51
workplans/llm-connect-WP-0003-functional-extensions.md
Normal file
@@ -0,0 +1,51 @@
|
||||
# LLM-WP-0003 — Functional Extensions (FR-2 + FR-1)
|
||||
|
||||
**status:** active
|
||||
**owner:** llm-connect
|
||||
**repo:** llm-connect
|
||||
**created:** 2026-04-01
|
||||
**depends-on:** LLM-WP-0001 (test infrastructure must exist)
|
||||
|
||||
## Purpose
|
||||
|
||||
Implement the two IHF feature requests that add new Functional-layer modules.
|
||||
Neither touches Core. Both can be developed independently of WP-0002.
|
||||
|
||||
Origin: IHUB-WP-0012 Phase 11 — Advanced AI Federation (completed 2026-04-01).
|
||||
|
||||
## GAAF notes
|
||||
|
||||
Both additions are Functional-layer under GAAF-2026:
|
||||
- Demand signal is explicit: IHF (inter-hub) is the primary consumer for both.
|
||||
- Each gets its own functional contract doc in `/contracts/functional/`.
|
||||
- Maturity on release: Beta (single known consumer, interface not yet stabilised).
|
||||
|
||||
## Tasks
|
||||
|
||||
### FR-2 — RoutingPolicy
|
||||
|
||||
| ID | Title | Priority | Status |
|
||||
|-----|-------|----------|--------|
|
||||
| T01 | `RoutingPolicy` data model: `rules` list with `task_type`, `prefer`, `max_cost_per_1k`, `fallback` | high | todo |
|
||||
| T02 | `policy.resolve(task_type)` → returns configured `LLMAdapter` | high | todo |
|
||||
| T03 | Export from `llm_connect.__init__` and update `__all__` | medium | todo |
|
||||
| T04 | Functional contract doc for `RoutingPolicy` | medium | todo |
|
||||
| T05 | Tests: rule match, cost-cap fallback, unknown task_type fallback, no-match default | high | todo |
|
||||
|
||||
### FR-1 — HTTP serve mode
|
||||
|
||||
| ID | Title | Priority | Status |
|
||||
|-----|-------|----------|--------|
|
||||
| T06 | Design `/execute` JSON schema (request: provider, model, prompt, config; response: LLMResponse fields) | high | todo |
|
||||
| T07 | Implement `llm_connect/server.py` — minimal HTTP server, `POST /execute`, `GET /health` | high | todo |
|
||||
| T08 | `python -m llm_connect.server --port N --provider X --model Y` CLI entry point | high | todo |
|
||||
| T09 | Add `httpx` or `aiohttp` server dep under `[project.optional-dependencies] server` | medium | todo |
|
||||
| T10 | Functional contract doc (API schema — request/response shapes, error codes) | medium | todo |
|
||||
| T11 | Tests: spin up server in subprocess or via `TestClient`, POST round-trip (MockAdapter), error responses | high | todo |
|
||||
|
||||
## Exit criteria
|
||||
|
||||
- `RoutingPolicy.resolve("triage")` returns the correct adapter per rules in tests
|
||||
- `python -m llm_connect.server --port 9999` starts and responds to `POST /execute`
|
||||
- `GET /health` returns 200
|
||||
- All functional contract docs present in `/contracts/functional/`
|
||||
Reference in New Issue
Block a user