How ebrahimabdelwahed/study-agent-harness works
Study Agent Harness is a provider-neutral Python library and reference CLI for building source-grounded study agents. Its main workflow is to create a local course, ingest source material, rebuild retrieval, then answer a question using retrieved evidence and an explicitly configured model; verified answers can be committed to a session. Canonical state is an append-only event stream, with projections and local indexes serving reads and recovery. The README documents additional assessment, artifact, lifecycle, and export capabilities. Sampled source supports several service boundaries; some CLI-to-service wiring is inferred only from the documented product workflow.
Main entry points: harness.py Repository harness · storage.py Domain event stream · grounding_ask.py Grounded answers · service.py Source ingestion
Components 22
User Interface
- Reference CLI
src/study_agent/cli/main.py - Repository harness
src/study_agent/application/harness.py - Desired-state lifecycle
src/study_agent/lifecycle/service.py - Portable export
src/study_agent/application/export.py
Study Workflow
- Source ingestion
src/study_agent/ingestion/service.py - Knowledge shaping
src/study_agent/knowledge - Evidence retrieval
src/study_agent/retrieval - Grounded answers
src/study_agent/application/grounding_ask.py - Study sessions
src/study_agent/sessions/service.py
Canonical State
- Course records
src/study_agent/courses/service.py - Study artifacts
src/study_agent/artifacts/service.py - Assessments
src/study_agent/assessments/service.py - Domain event stream
src/study_agent/ports/storage.py - Read projections
src/study_agent/ingestion/projection.py
Agent Runtime
- Playbook engine
src/study_agent/playbooks/engine.py - Capability dispatch
src/study_agent/capabilities/gateway.py - Isolated workers
src/study_agent/workers/service.py
Local Adapters
- SQLite stores
src/study_agent/adapters/sqlite - Filesystem adapters
src/study_agent/adapters/filesystem - Model adapter
src/study_agent/adapters/model/openai_compatible.py
Other components
- Operator / host
- Agent host
Connections 23
- Operator / host → Reference CLI: issues commands
- Reference CLI → Repository harness: dispatches requests
- Repository harness → Source ingestion: ingests sources
- Source ingestion → Domain event stream: commits revisions
- Source ingestion → Evidence retrieval: rebuilds index
- Evidence retrieval → Knowledge shaping: searches knowledge
- Repository harness → Grounded answers: handles ask
- Grounded answers → Evidence retrieval: retrieves evidence
- Grounded answers → Model adapter: requests generation
- Grounded answers → Study sessions: commits verified answer
- Study sessions → Domain event stream: appends events
- Course records → Domain event stream: appends events
- Study artifacts → Domain event stream: appends events
- Assessments → Domain event stream: appends events
- Domain event stream → Read projections: replayed into
- Repository harness → Playbook engine: runs study behavior
- Playbook engine → Capability dispatch: dispatches capabilities
- Isolated workers → Capability dispatch: executes isolated runs
- Desired-state lifecycle → Course records: plans canonical changes
- Repository harness → Portable export: exports course state
- SQLite stores → Domain event stream: implements event store
- Filesystem adapters → Repository harness: provides local repository
- Agent host → Repository harness: binds trusted context