generated from coulomb/repo-seed
169 lines
5.0 KiB
Markdown
169 lines
5.0 KiB
Markdown
---
|
||
id: CYA-WP-0008
|
||
type: workplan
|
||
title: "llm-connect Adapter Integration for Production Assistance"
|
||
domain: capabilities
|
||
repo: can-you-assist
|
||
status: ready
|
||
owner: grok
|
||
topic_slug: foerster-capabilities
|
||
created: "2026-06-22"
|
||
updated: "2026-06-22"
|
||
state_hub_workstream_id: "f713db12-5b90-4453-8fbb-a0e50f61699b"
|
||
---
|
||
|
||
# CYA-WP-0008: llm-connect Adapter Integration
|
||
|
||
## Goal
|
||
|
||
Replace `FakeLLMAdapter` on production code paths with a real **llm-connect** client
|
||
behind the existing `LLMAdapter` Protocol, so one-shot `cya "..."` and `cya shell`
|
||
(CYA-WP-0007) can deliver genuinely useful multi-turn assistance.
|
||
|
||
Preserve the seam: `cya` never hard-codes a vendor; all provider config lives in
|
||
llm-connect. Credential routing via `warden route` before requesting secrets.
|
||
|
||
## Background & References
|
||
|
||
- **Seam:** `src/cya/llm/adapter.py` — `LLMAdapter` Protocol + `FakeLLMAdapter`
|
||
- **INTENT.md:** `cya` asks; `llm-connect` reaches infrastructure
|
||
- **SCOPE.md:** real client listed as explicit out-of-scope / future work
|
||
- **CYA-WP-0007:** REPL usable with fake adapter for scaffolding; quality needs this slice
|
||
- **Credential routing:** `AGENTS.md` / `warden route find` — no secrets in repo
|
||
|
||
## Non-Goals
|
||
|
||
- Provider-specific UI inside `cya` (model picker beyond minimal config)
|
||
- Token billing dashboards or cost analytics
|
||
- Embedding / RAG pipelines
|
||
- Bypassing `LLMAdapter` Protocol for any production path
|
||
|
||
## Dependencies
|
||
|
||
- **llm-connect** package/API stability (coordinate with that repo owner)
|
||
- Operator-provided credentials via OpenBao paths surfaced by `warden route`
|
||
- CYA-WP-0007 T05 can proceed in parallel using `FakeLLMAdapter`
|
||
|
||
## Task Breakdown
|
||
|
||
### T01 — Adapter contract review and llm-connect API survey
|
||
|
||
```task
|
||
id: CYA-WP-0008-T01
|
||
status: todo
|
||
priority: high
|
||
state_hub_task_id: "483d13bb-aabe-48ad-96c2-8df83de5f442"
|
||
```
|
||
|
||
Document mapping from `AssistanceRequest` / `AssistanceResponse` to llm-connect calls.
|
||
Identify config surface (TOML keys, env vars). Note gaps requiring llm-connect changes.
|
||
|
||
**Acceptance criteria:**
|
||
- Short integration note in `docs/` or workplan appendix.
|
||
- Credential route catalog id(s) documented via `warden route find`.
|
||
|
||
### T02 — Implement `LLMConnectAdapter`
|
||
|
||
```task
|
||
id: CYA-WP-0008-T02
|
||
status: todo
|
||
priority: high
|
||
state_hub_task_id: "0fc17ad5-d90b-4ad1-b060-a1a2f9c25ea8"
|
||
```
|
||
|
||
New class in `src/cya/llm/` implementing `LLMAdapter`:
|
||
|
||
- Delegates to llm-connect client
|
||
- Graceful degrade message when llm-connect unavailable / misconfigured
|
||
- `FakeLLMAdapter` remains for tests and `--offline` mode
|
||
|
||
**Acceptance criteria:**
|
||
- Protocol-compliant; swap via config or env (`CYA_LLM_ADAPTER=connect|fake`).
|
||
|
||
### T03 — Configuration and developer ergonomics
|
||
|
||
```task
|
||
id: CYA-WP-0008-T03
|
||
status: todo
|
||
priority: medium
|
||
state_hub_task_id: "e8470a37-ecec-42f1-920b-ccd8b98b5512"
|
||
```
|
||
|
||
- `~/.config/cya/config.toml` `[llm]` section (backend, model hints)
|
||
- Document `warden route` steps in README
|
||
- `make dev-install` optional extra `[llm]` dependency group if needed
|
||
|
||
**Acceptance criteria:**
|
||
- Operator can configure adapter without editing source.
|
||
- No secrets committed; example config uses placeholders.
|
||
|
||
### T04 — Orchestrator and shell integration
|
||
|
||
```task
|
||
id: CYA-WP-0008-T04
|
||
status: todo
|
||
priority: high
|
||
state_hub_task_id: "f2781963-fecf-4576-96de-bd745df271a0"
|
||
```
|
||
|
||
Wire `handle_request()` and CYA-WP-0007 shell turns to adapter selection:
|
||
|
||
- Default fake when unconfigured (current behavior)
|
||
- Real adapter when config present
|
||
- Multi-turn context: pass recent session turns in `AssistanceRequest.context`
|
||
|
||
**Acceptance criteria:**
|
||
- One-shot and shell paths use same adapter factory.
|
||
- Session context bounded (token/line budget documented).
|
||
|
||
### T05 — Tests and offline CI strategy
|
||
|
||
```task
|
||
id: CYA-WP-0008-T05
|
||
status: todo
|
||
priority: high
|
||
state_hub_task_id: "32de980b-1a24-4159-9550-7c516570cae3"
|
||
```
|
||
|
||
- Mock llm-connect for unit tests (no live API in default `make test`)
|
||
- Optional integration test marker `@pytest.mark.llm_live` for manual runs
|
||
- Fake adapter remains default in CI
|
||
|
||
**Acceptance criteria:**
|
||
- `make test` passes without network or API keys.
|
||
- Live test documented for operator manual verification.
|
||
|
||
### T06 — Documentation and SCOPE update
|
||
|
||
```task
|
||
id: CYA-WP-0008-T06
|
||
status: todo
|
||
priority: medium
|
||
state_hub_task_id: "2d152d4b-e4b2-4a94-8f85-d8f033e55d5f"
|
||
```
|
||
|
||
Update README, SCOPE.md (remove "only FakeLLMAdapter" where accurate), AGENTS.md.
|
||
|
||
**Acceptance criteria:**
|
||
- Clear "configured vs offline" operator paths documented.
|
||
|
||
### T07 — Register, sync, and handoff
|
||
|
||
```task
|
||
id: CYA-WP-0008-T07
|
||
status: todo
|
||
priority: low
|
||
state_hub_task_id: "2fb42517-b2df-43d3-8195-f02d310107dc"
|
||
```
|
||
|
||
`make fix-consistency`, progress event, coordinate with llm-connect repo if API gaps found.
|
||
|
||
## Success Criteria
|
||
|
||
- Configured `cya` uses llm-connect for real inference.
|
||
- Unconfigured / test environments behave exactly as today (fake adapter).
|
||
- CYA-WP-0007 shell session becomes practically useful once both workplans complete.
|
||
|
||
---
|
||
|
||
**Status note:** `ready` on 2026-06-22. Can start T01–T03 in parallel with CYA-WP-0007 T02–T04. |