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	agents	can-you-assist	finished	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: 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

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

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

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

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

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

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.