generated from coulomb/repo-seed
tegwick
019f6e7dc7
Wire LLMConnectAdapter behind the existing LLMAdapter seam with config-driven selection, graceful degradation, --offline mode, and bounded session context. Add unit tests, integration docs, and update README/SCOPE/AGENTS.
246 lines
8.4 KiB
Markdown
246 lines
8.4 KiB
Markdown
# cya — console-native assistant for local work
|
||
|
||
`cya` lets you express intent in natural language from your terminal and receive
|
||
safe, explainable, context-aware help.
|
||
|
||
It is the CLI surface for the capabilities domain. It owns orchestration,
|
||
the user experience, and the safety layer. It talks to `llm-connect` only
|
||
through a stable adapter boundary and keeps all memory under explicit
|
||
user-controlled ports (implemented by `phase-memory`).
|
||
|
||
## Status
|
||
|
||
This is the first narrow MVP slice (CYA-WP-0001). The tool is already
|
||
usable after `pip install -e .`:
|
||
|
||
- `cya "your request in plain English"`
|
||
- `cya --explain-context "..."` — shows exactly what local context would be sent
|
||
- Automatic rule-based risk classification with mandatory confirmation for anything destructive, privileged, mass-edit, or network-affecting
|
||
- All LLM interaction flows through a documented `LLMAdapter` seam (`FakeLLMAdapter` by default; real `llm-connect` when configured)
|
||
|
||
## Installation
|
||
|
||
### 1. Install from Development Head (Recommended for Daily Use)
|
||
|
||
Stay on the absolute latest code with one command:
|
||
|
||
```bash
|
||
git clone https://github.com/worsch/can-you-assist.git
|
||
cd can-you-assist
|
||
make dev-install
|
||
```
|
||
|
||
Or the direct git method (no permanent clone needed):
|
||
|
||
```bash
|
||
pip install "git+https://github.com/worsch/can-you-assist.git@main#egg=can-you-assist[dev]"
|
||
```
|
||
|
||
After installing, `cya --version` will show a development version (e.g. `0.2.0.dev48+gf500a35...`).
|
||
|
||
### 2. Install a Released Version (Future)
|
||
|
||
Once we publish official releases:
|
||
|
||
```bash
|
||
pip install can-you-assist
|
||
# or a specific version
|
||
pip install "can-you-assist>=0.3.0"
|
||
```
|
||
|
||
See `docs/release-process.md` for how releases are cut.
|
||
|
||
### Updating
|
||
|
||
```bash
|
||
cd can-you-assist
|
||
git pull
|
||
make dev-install
|
||
```
|
||
|
||
## LLM backend (configured vs offline)
|
||
|
||
By default `cya` uses a deterministic **offline** adapter (no API keys, no network).
|
||
For real inference, configure llm-connect:
|
||
|
||
```bash
|
||
# 1. Install llm-connect (sibling checkout)
|
||
pip install -e ~/llm-connect
|
||
|
||
# 2. Route credentials — do not commit keys
|
||
warden route find "OpenRouter API key" --json
|
||
|
||
# 3. Export key and configure cya
|
||
export OPENROUTER_API_KEY="..." # from OpenBao / operator path
|
||
mkdir -p ~/.config/cya
|
||
cat > ~/.config/cya/config.toml <<'EOF'
|
||
[llm]
|
||
adapter = "connect"
|
||
backend = "openrouter"
|
||
model = "anthropic/claude-sonnet-4"
|
||
EOF
|
||
|
||
cya "show me the recent git history for this repo"
|
||
```
|
||
|
||
Force offline mode anytime (tests, CI, air-gapped):
|
||
|
||
```bash
|
||
cya --offline "your request"
|
||
# or: CYA_LLM_ADAPTER=fake cya "..."
|
||
```
|
||
|
||
See `docs/llm-connect-integration.md` for the full mapping, session context budget,
|
||
and optional `.cya.toml` project overrides.
|
||
|
||
## Usage examples
|
||
|
||
```bash
|
||
# Normal request (safe path)
|
||
cya "show me the recent git history for this repo"
|
||
|
||
# Risky request — will show classification + require explicit confirmation
|
||
cya "delete every log file older than 30 days in this tree"
|
||
|
||
# See exactly what context would be collected and sent
|
||
cya --explain-context "explain the changes in the last commit"
|
||
```
|
||
|
||
The output includes a structured suggestion, rationale, and (when relevant) a
|
||
clear preview + confirmation prompt. Nothing executes without your explicit yes.
|
||
|
||
## Safety (core product behavior)
|
||
|
||
- Genuine rule-based assessment is the primary mechanism.
|
||
- Results are available to the model.
|
||
- Anything above "safe" produces a preview and blocks until you confirm in the
|
||
launching terminal.
|
||
- No autonomous execution in this slice.
|
||
|
||
See the risk classifier tests and workplan T03 for the exact rules and invariants.
|
||
|
||
## Memory (T02 + T03 + T04 + 0003)
|
||
|
||
`cya` has real, user-controlled, context-aware memory that improves over time.
|
||
|
||
### Automatic Directory/Project-Bound Activation (T03)
|
||
|
||
Memory scoped to a directory or project is automatically activated when you work there.
|
||
|
||
```bash
|
||
# In your project directory, teach cya your preferences once
|
||
cya "remember that I always want the short git status with branch info"
|
||
|
||
# Later, in the same directory (or any subdirectory), cya will use it automatically
|
||
cya "show me the recent changes"
|
||
|
||
# No need to restate your preference — it is activated based on the working directory
|
||
```
|
||
|
||
See exactly what memory influenced a response:
|
||
```bash
|
||
cya --explain-context "show me the recent changes"
|
||
```
|
||
|
||
### Structured Retrospection & Continuous Improvement (T04)
|
||
|
||
Run a guided reflection session to review how memory was used and explicitly set goals for future interactions.
|
||
|
||
```bash
|
||
cya retrospect
|
||
```
|
||
|
||
During the session `cya` will:
|
||
- Show recent memory items that were activated.
|
||
- Help you reflect on what worked or didn't.
|
||
- Let you record new **interaction goals** (e.g. "be more concise", "always show one safe alternative for destructive commands").
|
||
- Optionally capture **1–3 verbal lessons** (Profile 1) with guided prompts, preview, and confirmation.
|
||
|
||
Example Profile 1 flow at the end of `cya retrospect`:
|
||
|
||
```
|
||
Capture 1–3 verbal lessons from this session? (y/n) y
|
||
What went well that you want to remember? (or 'skip') Safety warnings were clear
|
||
What should cya remember for next time? (or 'skip') Always suggest git status first
|
||
What should cya avoid in this scope? (or 'skip') skip
|
||
|
||
Preview — verbal lessons to save
|
||
1. [went well] Safety warnings were clear
|
||
2. [remember] Always suggest git status first
|
||
|
||
Save these lessons? (y/n) y
|
||
Saved 2 verbal reflection(s) (Profile 1).
|
||
```
|
||
|
||
These goals and lessons are stored as first-class memory and will influence future activations and responses.
|
||
|
||
### Inspecting and Controlling Memory
|
||
|
||
All memory is stored in plain, user-editable JSON:
|
||
```bash
|
||
~/.config/cya/memory/<scope>.json
|
||
```
|
||
|
||
Useful commands:
|
||
```bash
|
||
cya --explain-context "..." # See exactly what memory was activated and why
|
||
cya memory reflections # List verbal reflections for the current scope
|
||
cya memory reflections --json # Export reflections as JSON
|
||
# (You can also use the memory ports directly in Python if you want to script it.)
|
||
```
|
||
|
||
Memory also feeds the safety layer: a "never auto-run" preference you set during retrospection will still force mandatory confirmation.
|
||
|
||
### Architecture Notes
|
||
- Memory lives behind explicit ports in `src/cya/memory/__init__.py`.
|
||
- Activation is automatic based on cwd + git root (with full provenance).
|
||
- Retrospection outcomes are stored with special kinds (`retrospection`, `interaction_goal`) and get preferential treatment in future context building.
|
||
- Everything is designed to be replaced/enriched by a full `phase-memory` implementation later (see MemoryVision.md).
|
||
- **Profile 0** (post-0003 local JSON + activation + retrospection loop) is the stable foundation.
|
||
- **Profile 1** (verbal reflections) is production-ready as of CYA-WP-0006: guided capture in `cya retrospect`, `cya memory reflections`, compaction, and surfacing in responses / `--explain-context`.
|
||
- Profiles 2–3 (hierarchical synthesis, procedural rules) remain roadmap items — see MemoryVision.md.
|
||
|
||
See:
|
||
- `docs/cya-memory-activation-and-retrospection-concept.md` (the T01 design)
|
||
- `workplans/CYA-WP-0003-...md`
|
||
- `src/cya/memory/__init__.py`
|
||
- `MemoryVision.md` for the long-term phase-memory vision
|
||
|
||
All memory usage is visible, explainable, and under your control. Nothing is hidden or opaque.
|
||
|
||
## Architecture & boundaries (important)
|
||
|
||
- `can-you-assist` (this repo): CLI, context collection, safety, orchestration.
|
||
- `llm-connect`: Provider access, config, token counting, structured responses.
|
||
All interaction goes through `cya/llm/adapter.py` (`LLMAdapter` Protocol).
|
||
- `phase-memory`: Durable, user-controlled memory. Real (persisting) implementation
|
||
lives behind the explicit ports in `cya/memory/__init__.py` (T02). Signals also flow
|
||
into the rule-based risk layer (T04).
|
||
|
||
See `workplans/CYA-WP-0001-console-native-mvp.md` for the full task breakdown,
|
||
decisions, and integration guide.
|
||
|
||
## Development
|
||
|
||
```bash
|
||
# Recommended one-liner (see Installation section above)
|
||
make dev-install
|
||
pip install -e ~/llm-connect # optional, for live inference
|
||
|
||
pytest tests/ -q # offline mocks only; no API keys
|
||
pytest -m llm_live # manual live check (requires OPENROUTER_API_KEY)
|
||
cya --offline "..." # manual verification without network
|
||
make version # show current dev version
|
||
```
|
||
|
||
## License
|
||
|
||
MIT (see LICENSE).
|
||
|
||
## Workplan & coordination
|
||
|
||
- Workplan: `workplans/CYA-WP-0001-console-native-mvp.md`
|
||
- State Hub workstream: `repo-integration-can-you-assist`
|
||
- Operator reminder after changes: `cd ~/state-hub && make fix-consistency REPO=can-you-assist`
|
||
|