spectra-ai 0.3.1

8 AI agents analyze your entire repository in under 5 minutes

SPECTRA

The full spectrum of your codebase

Spectra grades any repository on architecture, security, quality, docs, maintainability, and performance — in under 5 minutes. It runs 8 specialized Claude agents in parallel (Opus 4.7) so you get a full audit instead of a single linter's opinion. Built for developers running self-checks, teams gating PRs in CI, and reviewers who need a second pair of eyes before merge.

Quickstart · What You Get · Compare · Architecture · CLI Reference

---

Quickstart

Three lines, under a minute:

pip install spectra-ai
export ANTHROPIC_API_KEY=sk-ant-...
spectra analyze https://github.com/your/repo

Open spectra-report.html when it finishes. Requires Python 3.12+ and an Anthropic API key.

Drop into any GitHub Action

- uses: spectra-ai/spectra@v1
  with:
    anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}

---

The Problem

AI-generated code ships faster than ever, but quality assurance hasn't kept up. One LLM call can't catch architecture drift, security flaws, and documentation gaps at the same time.

Spectra deploys 8 AI agents — 6 parallel specialists, a planning agent, and a critique agent — to give you the full spectrum in under 5 minutes.

---

What You Get

A weighted ScoreCard plus a self-contained HTML report. Here's what the terminal looks like at the end of a run:

▸ INGEST: cloned expressjs/express (1,247 files, 184K LOC)
▸ PLAN:   MetaPrompter built 6-agent plan (4.2K tokens)
▸ ANALYZE: 6 specialists running in parallel...
   ✓ Architecture     12.4s   8 findings
   ✓ Security          9.8s   14 findings (3 critical)
   ✓ Quality          11.2s   11 findings
   ✓ Documentation     7.6s   6 findings
   ✓ Maintainability   8.1s   4 findings
   ✓ Performance      10.5s   3 findings
▸ MERGE:    deduplicated 46 → 38 findings
▸ CRITIQUE: validated findings, dropped 4 false positives (Opus 4.7 + thinking)
▸ REPORT:   spectra-report.html

┌─────────────────────────────────────────────┐
│  SPECTRA SCORECARD                          │
│  repo: expressjs/express                    │
│  Overall: B- (80/100)                       │
├─────────────────────────────────────────────┤
│  Architecture   █████████░  89  A-          │
│  Security       ██████░░░░  67  D+          │
│  Quality        █████████░  87  B+          │
│  Documentation  ██████░░░░  68  C-          │
│  Maintainability██████████  92  A           │
│  Performance    ████████░░  76  C+          │
├─────────────────────────────────────────────┤
│  34 findings · 3 critical · 87s · $2.41     │
└─────────────────────────────────────────────┘

✓ Top issues: SQL injection in middleware/parser.js:142
              prototype pollution in utils/merge.js:38
              missing auth on /admin/* routes

See Spectra analyze itself: spectra-self-report.html — B+ (86/100), 60 findings, $9.24

---

Three Things That Set Spectra Apart

8 AI agents in parallel	Incremental cache	GitHub Action
Six specialists (architecture, security, quality, docs, maintainability, performance) plus a MetaPrompter planner and a CritiqueAgent that filters false positives. All Opus 4.7. Specialists fan out via asyncio.gather so the wall clock is the slowest agent, not the sum.	Re-run the same repo and finish in seconds. Composite-key cache (content × dimension × model × prompt × schema × spectra version) means only changed files re-analyze. Three subcommands manage it: spectra cache stats / clear / prune.	Drop spectra-ai/spectra@v1 into any PR workflow with one block of YAML. The Action installs from PyPI, runs spectra analyze, and posts SARIF to the GitHub Security tab. Min-score gate fails the build below threshold.

Other things you get

• Multi-model strategy — Opus 4.7 (medium effort) for planning, Opus 4.7 (xhigh effort) for deep analysis, Opus 4.7 with adaptive thinking for critique
• Self-contained HTML reports — Radar charts, interactive findings, keyboard navigation, file hotspot heatmaps — one file, works offline
• Due diligence frameworks — OWASP Top 10, SOC 2 Trust Criteria, PCI DSS 4.0, NIST CSF 2.0, and Investment Readiness scoring
• Cost transparency — Every report shows exact token usage and dollar cost
• Clean Architecture — 4-layer dependency rule, frozen Pydantic models, zero Any types — the tool that audits architecture follows strict architecture itself

---

How Spectra Compares

Honest tradeoffs. Spectra is built for full-repo audits — not for inline PR comments or IDE feedback. Use it alongside, not instead of, the tools your team already runs.

	Spectra	CodeRabbit	DeepSource	Sourcery	Codeball
Whole-repo audit (one report, six dimensions)	✓	partial	partial	—	—
Multiple specialist agents in parallel	✓ (8)	—	—	—	—
False-positive filtering pass	✓ (CritiqueAgent)	—	—	—	—
Self-contained HTML report (offline)	✓	—	—	—	—
SARIF output for GitHub Security tab	✓	—	✓	—	—
Compliance scoring (OWASP / SOC 2 / PCI DSS / NIST)	✓	—	partial	—	—
Incremental cache (re-runs in seconds)	✓	—	✓	—	—
Inline PR comments on diffs	—	✓	✓	✓	✓
IDE plugin (VS Code, JetBrains)	—	—	—	✓	—
Real-time review on every push	—	✓	✓	—	✓
Pricing model	Per-run API cost ($1-10)	SaaS subscription	SaaS subscription	SaaS subscription	SaaS subscription
Open source (MIT)	✓	—	—	—	—

If you need inline PR comments while reviewing diffs, run CodeRabbit. If you need an architecture-level audit with security and compliance scoring before a release or due-diligence review, run Spectra. They complement each other.

---

How It Works

graph LR
    A[INGEST<br/>Clone repo] --> B[PLAN<br/>MetaPrompter<br/>Opus 4.7 medium]
    B --> C[ANALYZE<br/>6 Specialists<br/>Opus 4.7 xhigh]
    C --> D[MERGE<br/>Deduplicate<br/>& Score]
    D --> E[CRITIQUE<br/>CritiqueAgent<br/>Opus 4.7 adaptive]
    E --> F[REPORT<br/>HTML + Charts<br/>ScoreCard]

    style A fill:#7C3AED,stroke:#7C3AED,color:#fff
    style B fill:#7C3AED,stroke:#7C3AED,color:#fff
    style C fill:#F59E0B,stroke:#F59E0B,color:#fff
    style D fill:#7C3AED,stroke:#7C3AED,color:#fff
    style E fill:#EF4444,stroke:#EF4444,color:#fff
    style F fill:#22C55E,stroke:#22C55E,color:#fff

The ANALYZE stage fans out to 6 parallel specialists:

graph TD
    MP[MetaPrompter Plan] --> ARCH[Architecture Agent]
    MP --> SEC[Security Agent]
    MP --> QUAL[Quality Agent]
    MP --> DOC[Documentation Agent]
    MP --> DEP[Dependency Agent]
    MP --> PERF[Performance Agent]

    ARCH --> MERGE[Merge & Score]
    SEC --> MERGE
    QUAL --> MERGE
    DOC --> MERGE
    DEP --> MERGE
    PERF --> MERGE

    style MP fill:#7C3AED,stroke:#7C3AED,color:#fff
    style MERGE fill:#F59E0B,stroke:#F59E0B,color:#fff

---

Agent Roster

Agent	Model	Role
MetaPrompter	Opus 4.7 (medium effort)	Reads file tree (never full code), builds analysis plan
ArchitectureAgent	Opus 4.7	Layering, coupling, dependency analysis
SecurityAgent	Opus 4.7	OWASP Top 10, CWE mapping, vulnerability detection
QualityAgent	Opus 4.7	Code smells, complexity, test coverage gaps
DocumentationAgent	Opus 4.7	API docs, README quality, inline comments
DependencyAgent	Opus 4.7	Supply chain, outdated packages, license risks
PerformanceAgent	Opus 4.7	N+1 queries, memory leaks, async anti-patterns
CritiqueAgent	Opus 4.7 + Adaptive Thinking	Validates all findings, removes false positives

---

ScoreCard

Every analysis produces a weighted ScoreCard:

Dimension	Weight	Agent
Architecture	25%	ArchitectureAgent
Security	25%	SecurityAgent
Quality	20%	QualityAgent
Documentation	10%	DocumentationAgent
Maintainability	10%	DependencyAgent
Performance	10%	PerformanceAgent

Grades: A+ (95-100) · A (90-94) · A- (87-89) · B+ (83-86) · B (80-82) · B- (77-79) · C+ (73-76) · C (70-72) · C- (67-69) · D+ (63-66) · D (60-62) · D- (57-59) · F (0-56)

---

Report Features

Every analysis generates a self-contained HTML report with:

• Executive summary — Top strengths and concerns at a glance
• Radar chart — Scores across all 6 dimensions
• Interactive findings — Filter by severity/dimension, text search, keyboard navigation (j/k, o, /)
• File hotspot heatmap — Files ranked by finding density
• Technical debt quantification — Estimated hours and cost to remediate
• ROI analysis — Estimated return on fixing identified issues
• Compliance mapping — OWASP Top 10, SOC 2, PCI DSS 4.0, NIST CSF 2.0

Works offline. No external dependencies. One HTML file. Print-friendly for PDF export.

---

Architecture

System context

Spectra in its environment — who invokes it and what it talks to. Two install paths (local pip + GitHub Action), one PyPI package. Source: docs/diagrams/system-context.md.

flowchart LR
    classDef person      fill:#dbeafe,stroke:#1e3a8a,stroke-width:2px,color:#1e293b
    classDef system      fill:#ede9fe,stroke:#7C3AED,stroke-width:4px,color:#1e293b
    classDef external    fill:#fef3c7,stroke:#92400e,stroke-width:2px,color:#1e293b
    classDef storage     fill:#dcfce7,stroke:#166534,stroke-width:2px,color:#1e293b
    classDef distribution fill:#fef3c7,stroke:#92400e,stroke-width:2px,color:#1e293b

    Dev["<b>Developer</b><br/>[Person]<br/>Runs spectra analyze<br/>from a terminal"]:::person
    PR["<b>GitHub PR</b><br/>[External CI]<br/>pull_request event<br/>invokes the Action"]:::person

    Spectra(["<b>Spectra CLI</b><br/>[Software System]<br/>8 AI agents · 6 dimensions<br/>Clean Architecture · Python 3.12+<br/>5-stage pipeline + cache"]):::system

    Anthropic["<b>Anthropic API</b><br/>[External SaaS]<br/>Claude Opus 4.7<br/>all 8 agents"]:::external
    GitHub["<b>GitHub.com</b><br/>[External Service]<br/>Git clone source<br/>HTTPS only"]:::external
    PyPI["<b>PyPI</b><br/>[Distribution]<br/>pip install spectra-ai<br/>also installed by Action"]:::distribution
    FS[("<b>Local Filesystem</b><br/>[OS]<br/>~/.cache/spectra/cache.db (SQLite WAL)<br/>spectra-report.{html,json,sarif}")]:::storage

    Dev      -- "spectra analyze ."          --> Spectra
    PR       -- "uses: spectra-ai/spectra@v1" --> Spectra
    Spectra  -- "HTTPS · streaming /messages" --> Anthropic
    Spectra  -- "git clone (depth=1)"        --> GitHub
    Spectra  <-- "cache R/W · report write"  --> FS
    PyPI     -. "install (cold path)"        .-> Spectra

Clean Architecture layers

Four strict layers with one rule:

graph TB
    subgraph "Layer 4 — Infrastructure"
        INF[Anthropic API · Git · Tokens · Agents]
    end
    subgraph "Layer 3 — Adapters"
        ADP[CLI · Rich Terminal · HTML Presenter]
    end
    subgraph "Layer 2 — Use Cases"
        UC[Pipeline Orchestration · Protocol Interfaces]
    end
    subgraph "Layer 1 — Entities"
        ENT[Domain Models · Enums · Errors]
    end

    INF --> ADP
    INF --> UC
    INF --> ENT
    ADP --> UC
    ADP --> ENT
    UC --> ENT

    style ENT fill:#22C55E,stroke:#22C55E,color:#fff
    style UC fill:#7C3AED,stroke:#7C3AED,color:#fff
    style ADP fill:#F59E0B,stroke:#F59E0B,color:#fff
    style INF fill:#EF4444,stroke:#EF4444,color:#fff

The dependency rule: Source code dependencies only point inward. No exceptions.

Design Patterns

Pattern	Where	Why
Facade	AnalyzeRepository	Orchestrates the 6-stage pipeline behind one call
Strategy	Agent implementations	Swap agents via factory without touching orchestrator
Decorator	LLM call chain	Logging → Retry → Anthropic adapter (composable)
Observer	ProgressObserver	Rich terminal updates decoupled from business logic
Template Method	BaseAgent	Common agent lifecycle, specialized per dimension
Composition Root	main.py	All dependencies wired at startup, no service locator

---

How Spectra Uses Claude

Multi-Model Strategy

Agent	Model	Why This Model
MetaPrompter	Opus 4.7 (medium effort)	Planning from file tree — fast, no deep reasoning needed
6 Specialists	Opus 4.7 (xhigh effort)	Deep code understanding across all 6 dimensions
CritiqueAgent	Opus 4.7 + Adaptive Thinking	Meta-reasoning to validate findings and reject false positives

Key Capabilities Used

• Parallel execution — 6 agents via asyncio.gather with semaphore rate limiting
• Token budget management — 800K tokens distributed by MetaPrompter's plan
• Adaptive thinking — CritiqueAgent reasons through each finding before passing judgment
• Structured output — Every agent returns Pydantic-validated JSON
• Prompt engineering — Few-shot JSON examples, hallucination guardrails, CWE/OWASP references
• Graceful degradation — If 2+ agents fail, partial report in DEGRADED state

---

Technology Stack

Component	Technology
Language	Python 3.12+
AI Models	Claude Opus 4.7 (all 8 agents)
AI SDK	anthropic Python SDK
CLI Framework	Typer
Terminal UI	Rich
Data Models	Pydantic v2 (frozen)
Git Operations	GitPython
Token Counting	tiktoken
Report Rendering	Jinja2
HTTP Client	httpx
Testing	pytest, pytest-asyncio
Linting	Ruff (40+ rules), mypy (strict)

---

Numbers That Matter

Metric	Value
Tests	1,096 passed
Coverage	97%
Agents	8 (6 parallel + MetaPrompter + CritiqueAgent)
Dimensions	6
Cost	$1-10 per analysis
Speed	Under 5 minutes end-to-end
Architecture	Clean Architecture, 4 layers
Error codes	10 typed (SPEC-001 to SPEC-010)

---

CI Integration

The official GitHub Action installs Spectra from PyPI and runs spectra analyze on every PR — no Python setup, no extra steps. See docs/github-action.md for the full reference.

# .github/workflows/spectra-analyze.yml
name: Spectra Analysis
on:
  pull_request:
    branches: [main]
jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: spectra-ai/spectra@v1
        with:
          min-score: 70
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

The Action also writes SARIF, which GitHub picks up under the Security tab — findings show inline on the PR.

---

CLI Reference

Two top-level commands: spectra analyze and spectra cache.

spectra analyze

spectra analyze <repo-url-or-path> [flags]

The argument can be an HTTPS Git URL, a local path, or . for the current working tree (no clone).

Flag	Default	Purpose
--quick	off	Skip the CritiqueAgent pass (saves ~40s, keeps false positives)
--format	html	Output format: html, json, or sarif
--output	spectra-report.html	Custom report path
--min-score	none	Quality gate — exit 1 if overall score is below this number
--force	off	Bypass cache, force a fresh analysis
--no-cache	off	Disable cache reads and writes for this run

spectra cache

Spectra writes a SQLite cache to ${XDG_CACHE_HOME:-~/.cache}/spectra/cache.db (WAL mode). Three subcommands manage it:

Subcommand	What it does
spectra cache stats	Show entry count, on-disk size, per-dimension hit rate (rolling last 100 lookups)
spectra cache clear	Drop all cache entries (full reset)
spectra cache prune	Physically delete stale rows that no current key matches — safe to run anytime

Cache I/O failures are never fatal — the pipeline degrades to no-cache for the rest of the run (see SPEC-010).

---

Contributing

# Clone and install
git clone https://github.com/leocder07/spectra.git
cd spectra
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Lint
ruff check src/ tests/
mypy src/

PRs welcome. Please follow the Clean Architecture dependency rule — it's enforced.

---

Built for the Anthropic Build with Claude Hackathon

Built with Claude Opus 4.7 and Claude Code.

MIT License · Repository