generated from coulomb/repo-seed
tegwick
a0f79af2ab
- Align agent files with on-disk workplan prefixes (infer from workplan ids) - Set workplan domain to registered domain_slug; add topic_slug where applicable - Repair frontmatter delimiter formatting; migrate legacy task status literals - Regenerate AGENTS.md, CLAUDE.md, and .claude/rules from State Hub templates
179 lines
5.4 KiB
Markdown
179 lines
5.4 KiB
Markdown
---
|
|
id: CYA-WP-0008
|
|
type: workplan
|
|
title: "llm-connect Adapter Integration for Production Assistance"
|
|
domain: agents
|
|
repo: can-you-assist
|
|
status: finished
|
|
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: done
|
|
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`.
|
|
|
|
**Delivered:** `docs/llm-connect-integration.md`
|
|
|
|
### T02 — Implement `LLMConnectAdapter`
|
|
|
|
```task
|
|
id: CYA-WP-0008-T02
|
|
status: done
|
|
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`).
|
|
|
|
**Delivered:** `src/cya/llm/connect_adapter.py`, `src/cya/llm/factory.py`
|
|
|
|
### T03 — Configuration and developer ergonomics
|
|
|
|
```task
|
|
id: CYA-WP-0008-T03
|
|
status: done
|
|
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.
|
|
|
|
**Delivered:** `src/cya/config.py`, `docs/cya-config.example.toml`, README section
|
|
|
|
### T04 — Orchestrator and shell integration
|
|
|
|
```task
|
|
id: CYA-WP-0008-T04
|
|
status: done
|
|
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).
|
|
|
|
**Delivered:** `get_adapter()` wired in orchestrator; `session_turns` + `bound_session_turns()` ready for CYA-WP-0007 shell
|
|
|
|
### T05 — Tests and offline CI strategy
|
|
|
|
```task
|
|
id: CYA-WP-0008-T05
|
|
status: done
|
|
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.
|
|
|
|
**Delivered:** `tests/test_llm_factory.py`, `tests/test_llm_connect_adapter.py`, `tests/test_llm_prompt.py`
|
|
|
|
### T06 — Documentation and SCOPE update
|
|
|
|
```task
|
|
id: CYA-WP-0008-T06
|
|
status: done
|
|
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: done
|
|
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:** `finished` on 2026-06-22. Integration doc: `docs/llm-connect-integration.md`. |