can-you-assist/workplans/CYA-WP-0008-llm-connect-adapter-integration.md

id, type, title, domain, repo, status, owner, topic_slug, created, updated, state_hub_workstream_id

id	type	title	domain	repo	status	owner	topic_slug	created	updated	state_hub_workstream_id
CYA-WP-0008	workplan	llm-connect Adapter Integration for Production Assistance	capabilities	can-you-assist	ready	grok	foerster-capabilities	2026-06-22	2026-06-22	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

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

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

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

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

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

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

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.