Strata builds a multi-layer graph of a software system, then runs explainable agents over that graph.
It is not just a code scanner. The graph connects code structure, Git history, service ownership, runtime dependencies, incidents, and business capabilities so analysis can explain why a risk matters and where the evidence came from.
- Ingest
strata.yml, local repositories, Git history, Python code structure, and JSON/CSV incident files into a property graph. - Run the Ownership-Weighted Technical Debt agent using transparent weighted scoring across complexity, churn, ownership diffusion, test gaps, and incident history.
- Run the Security Review Candidate agent using deterministic security signals, with optional LLM verification over bounded source slices.
- Store findings in a communal JSON file so rerunning one agent preserves the latest results from other agents.
- Inspect graph stats and findings through the CLI, FastAPI API, or server-rendered UI.
- Python 3.11+
For local development:
python -m pip install -e ".[dev]"Optional LLM provider extras:
python -m pip install -e ".[llm-openai]"
python -m pip install -e ".[llm-anthropic]"
python -m pip install -e ".[llm]"On Windows, the one-step installer performs a user-scoped editable install and
adds the Python Scripts directory to PATH:
scripts\install-windows.cmd
scripts\install-windows.cmd --extras dev,llm-openaiCreate and validate a starter config:
strata init
strata config validate --config strata.ymlRun ingestion and all registered agents:
strata ingest --config strata.yml
strata run all --config strata.yml --store-path .strata/findings.jsonInspect results:
strata graph stats --config strata.yml
strata findings list --store-path .strata/findings.json
strata findings show <finding-id> --store-path .strata/findings.jsonOpen the preloaded UI:
strata ui --config strata.yml --findings-store-path .strata/findings.json --port 8765Then visit http://127.0.0.1:8765/ui/.
| Task | Command |
|---|---|
| Plain-text CLI help | strata help |
| Write config template | strata config template --output strata.yml |
| Write local-LLM starter config | strata init --with-llm-local |
| Run debt agent | strata run debt --config strata.yml |
| Run security agent offline | strata run security --config strata.yml --no-llm |
| Force LLM-assisted run | strata run security --config strata.yml --llm |
| Run every registered agent | strata run all --config strata.yml |
| Start API directly | uvicorn strata.api.app:app --reload |
The legacy commands strata run-agent <agent> and strata run-all-agents are
still available. The shorter strata run ... aliases are preferred for day-to-day
use.
A minimal Strata config declares the system, repositories, services, teams,
capabilities, incident sources, and agent settings. Relative paths are resolved
from the directory containing strata.yml.
system:
name: demo-commerce
repositories:
- name: billing-service
path: ./billing-service
service: billing
services:
- id: billing
name: Billing Service
owns:
team: payments
teams:
- id: payments
name: Payments Team
capabilities:
- id: payments
name: Payments
implemented_by:
- billing
incidents: []
agents:
debt:
enabled: true
thresholds:
high_risk: 0.75
medium_risk: 0.5See docs/config.md for the full strict schema, defaults, LLM options, and graph-store configuration.
Run the API directly:
uvicorn strata.api.app:app --reloadThe direct API server starts with an empty in-memory service. Use POST /ingest
and the agent run endpoints to populate it, or use strata ui to start a server
that preloads a config and findings store.
Main API routes:
GET /healthGET /graph/statsGET /findingsGET /findings/{id}GET /nodes/{id}GET /nodes/{id}/neighborsPOST /ingestPOST /agents/debt/runPOST /agents/security/run
Hybrid-agent run endpoints accept use_llm: true | false | null.
By default Strata uses an in-memory graph for each process run. Use SQLite to persist graph data across commands:
graph_store:
adapter: sqlite
path: .strata/graph.dbEnvironment variables can override the file:
STRATA_GRAPH_ADAPTER=sqlite
STRATA_GRAPH_PATH=.strata/graph.dbIncident sources declared in strata.yml can be JSON or CSV files. Supported
fields are incident_id, title, severity, timestamp, status,
linked_services, linked_repositories, linked_files, tags, and summary.
Only incident_id and title are required.
| Doc | Contents |
|---|---|
| docs/architecture.md | Pipeline, module boundaries, invariants, ingestion orchestration |
| docs/graph-schema.md | Node types, edge types, deterministic IDs, graph adapters |
| docs/config.md | Complete strata.yml reference and validation behavior |
| docs/cli.md | CLI install, quickstart, commands, LLM flags, troubleshooting |
| docs/extractors.md | Extractor protocol, canonical events, adding extractors |
| docs/agents.md | Agent interface, built-in agents, scoring, LLM gating |
| docs/api-ui.md | API routes, request bodies, UI startup modes |
| docs/improvement-backlog.md | Prioritized product, platform, refactoring, quality, and documentation ideas |
| docs/four-person-plan-i01-i11.md | Parallel workstreams, file ownership, dependencies, and integration plan for backlog items I01-I11 |
When changing public behavior, update the docs closest to that surface and run the checks below.
pytest
ruff check .
mypy strataUseful documentation accuracy checks:
pytest tests/test_docs_examples.py
strata config template --output .strata/doc-check.yml --force
strata config validate --config .strata/doc-check.yml
strata help