Skip to content
benzae1Public

About

No description, website, or topics provided.

Resources

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

86 Commits

Folders and files

Repository files navigation

Strata

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.

Current Capabilities

  • 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.

Requirements

  • Python 3.11+

Install

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-openai

Quickstart

Create and validate a starter config:

strata init
strata config validate --config strata.yml

Run ingestion and all registered agents:

strata ingest --config strata.yml
strata run all --config strata.yml --store-path .strata/findings.json

Inspect results:

strata graph stats --config strata.yml
strata findings list --store-path .strata/findings.json
strata findings show <finding-id> --store-path .strata/findings.json

Open the preloaded UI:

strata ui --config strata.yml --findings-store-path .strata/findings.json --port 8765

Then visit http://127.0.0.1:8765/ui/.

Common Commands

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.

Configuration Shape

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.5

See docs/config.md for the full strict schema, defaults, LLM options, and graph-store configuration.

API And UI

Run the API directly:

uvicorn strata.api.app:app --reload

The 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 /health
  • GET /graph/stats
  • GET /findings
  • GET /findings/{id}
  • GET /nodes/{id}
  • GET /nodes/{id}/neighbors
  • POST /ingest
  • POST /agents/debt/run
  • POST /agents/security/run

Hybrid-agent run endpoints accept use_llm: true | false | null.

Persistent Graph

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.db

Environment variables can override the file:

STRATA_GRAPH_ADAPTER=sqlite
STRATA_GRAPH_PATH=.strata/graph.db

Incident Files

Incident 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.

Documentation

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.

Development Checks

pytest
ruff check .
mypy strata

Useful 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

About

No description, website, or topics provided.

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages