%%{init: {"theme": "base", "themeVariables": {"primaryColor": "#1e3a5f", "primaryTextColor": "#ffffff", "primaryBorderColor": "#0d2137", "lineColor": "#4a9eca", "secondaryColor": "#2d6a4f", "tertiaryColor": "#7b2d8b"}}}%%
flowchart TD
    classDef input    fill:#7b2d8b,stroke:#4a1a54,color:#fff,font-size:13px
    classDef mcp      fill:#e07b00,stroke:#9a5700,color:#fff,font-size:13px
    classDef agent    fill:#1a6b8a,stroke:#0d3f52,color:#fff,font-size:13px
    classDef core     fill:#2d6a4f,stroke:#1b4332,color:#fff,font-size:13px
    classDef graph    fill:#1e3a5f,stroke:#0d1f3c,color:#fff,font-size:13px
    classDef validate fill:#4a6741,stroke:#2d4026,color:#fff,font-size:13px
    classDef ok       fill:#155724,stroke:#0a3015,color:#fff,font-size:13px
    classDef reject   fill:#721c24,stroke:#3d0a0e,color:#fff,font-size:13px

    NL["🌎 Free-form NL\n(generate_java_test_nlp)"]:::input
    SF["📄 Structured fields\n(generate_java_test)"]:::input
    TX["💬 Intent text\n(generate_java_test_from_intent)"]:::input

    MCP["🔌 FastMCP stdio Server\n7 tools · zero raw Cypher"]:::mcp

    A1["🤖 LLMIntentParser\nAgent 1 · gpt-4o-mini\nfield extraction"]:::agent
    INT["✅ GenerationIntent\nclass · package · module\nconfig · version"]:::core
    GDB["📊 Graph Catalog\nNeo4j 5.26 / JSON fixture\n8 symbols · 12 methods"]:::graph
    GEN["⚙️ Template Generator\ndeterministic render"]:::core
    VAL["🛡️ JavaValidator\nTree-sitter AST\ncontract · grounding\nsource-safety"]:::validate
    A2["🤖 ReviewAgent\nAgent 2 · gpt-4o-mini\n6-item checklist"]:::agent

    OK["✅ Accepted Java\nsource + citations\n+ review verdict"]:::ok
    REJ["❌ Typed Rejection\nerror code + message\nno source returned"]:::reject

    NL --> MCP
    SF --> MCP
    TX --> MCP
    MCP -->|"NLP path"| A1
    MCP -->|"direct path"| INT
    A1 -->|"extracted fields"| INT
    INT -->|"invalid"| REJ
    INT -->|"valid"| GDB
    GDB -->|"cited symbols"| GEN
    GEN --> VAL
    VAL -->|"any gate fails"| REJ
    VAL -->|"all gates pass"| A2
    A2 -->|"issues found"| REJ
    A2 -->|"approved"| OK

%%{init: {"theme": "base", "themeVariables": {"actorBkg": "#1e3a5f", "actorTextColor": "#ffffff", "actorBorderColor": "#4a9eca", "activationBkgColor": "#2d6a4f", "activationBorderColor": "#155724", "noteBkgColor": "#fff8e1", "noteTextColor": "#333", "signalColor": "#4a9eca", "signalTextColor": "#1e3a5f"}}}%%
sequenceDiagram
    autonumber
    actor User
    participant MCP as FastMCP Server
    participant A1  as LLMIntentParser<br/>(Agent 1)
    participant GDB as Graph Catalog<br/>(Neo4j / Fixture)
    participant GEN as Generator +<br/>JavaValidator
    participant A2  as ReviewAgent<br/>(Agent 2)

    User->>MCP: generate_java_test_nlp(free-form NL)
    MCP->>A1: extract intent fields
    Note over A1: gpt-4o-mini · temp=0<br/>strict JSON schema
    A1-->>MCP: {class, package, module, config, version}
    MCP->>GDB: get versioned symbols
    GDB-->>MCP: 7 cited GraphSymbol objects
    MCP->>GEN: render Java + validate
    Note over GEN: Tree-sitter AST<br/>contract · grounding · safety
    GEN-->>MCP: validated Java source
    MCP->>A2: review(source, class, package)
    Note over A2: gpt-4o-mini · temp=0<br/>6-item checklist
    A2-->>MCP: {approved, checklist, issues}
    MCP-->>User: {status, source, citations, review}

%%{init: {"theme": "base", "themeVariables": {"quadrant1Fill": "#155724", "quadrant2Fill": "#856404", "quadrant3Fill": "#721c24", "quadrant4Fill": "#856404"}}}%%
xychart-beta
    title "Validation: task success vs safe-rejection recall (%)"
    x-axis ["no_graph_v0", "lenient_repair_v1", "strict_graph_v2 ✓", "wide_context_v3"]
    y-axis "Task success (%)" 0 --> 105
    bar  [21.9, 75.0, 100.0, 96.9]
    line [87.5,  0.0, 100.0, 87.5]

python -m venv .venv
# Windows
.\.venv\Scripts\Activate.ps1
# Linux / macOS
source .venv/bin/activate

pip install -r requirements-dev.txt
pip install --no-deps -e .

# Run the offline smoke test (no database needed)
python scripts/container_smoke.py python -m graph_mcp.server

{
  "mcpServers": {
    "graph-java-gen": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["-m", "graph_mcp.server"],
      "cwd": "/absolute/path/to/repo"
    }
  }
}

# Add to your environment or .env file
OPENAI_API_KEY=sk-...
GRAPH_BACKEND=neo4j   # optional; defaults to local JSON fixture

# Build the CC0 benchmark fixture
python scripts/build_evaluation_fixture.py

# Run all four candidate policies and select strict_graph_v2
python scripts/evaluate_workflow.py

# Validate the claims ledger and evidence privacy rules
python scripts/validate_evidence.py

# Full test suite
pytest --cov=src --cov-report=term-missing --cov-fail-under=75

# Lint and security
ruff check src tests scripts
bandit -r src scripts -q -ll
pip-audit -r requirements.txt --progress-spinner off

# Start a local Neo4j Community instance (Docker)
docker compose up -d neo4j
python scripts/wait_for_neo4j.py

# Seed the synthetic graph fixture and verify retrieval
python scripts/seed_graph.py
python scripts/verify_neo4j.py   # writes evidence/neo4j_integration.json

# Full MCP benchmark over stdio with live graph
python scripts/benchmark_mcp.py  # writes evidence/mcp_benchmark.json

# Requires JDK 21 on PATH
python scripts/compile_generated.py --require-compiler
# Writes evidence/java_compile.json

src/graph_mcp/
  workflow.py            intent parsing · graph lookup · Java generation · validation
  graph_store.py         Neo4j catalog adapter (parameterised Cypher)
  llm_intent_parser.py   Agent 1 — LLM free-form NL → GenerationIntent
  review_agent.py        Agent 2 — LLM post-generation checklist reviewer
  server.py              FastMCP stdio server (7 tools)
  evaluation.py          candidate scoring and selection harness

fixtures/
  synthetic_graph.json   CC0 versioned framework symbol catalog (SHA-256 bound)
  evaluation_cases.json  96 CC0 natural-language intents (32/32/32 split)
  java_framework/        7 independently generated Java stub classes

evidence/
  claims.json            machine-readable claims ledger (14 public claims)
  evaluation_protocol.json  pre-declared selection rules and safety gates
  task_evaluation.json   per-candidate, per-split, per-case results
  evaluation_trace.json  confirmation case-level trace
  neo4j_integration.json live Neo4j integration result
  mcp_benchmark.json     MCP protocol benchmark (120 calls)
  java_compile.json      ECJ compilation result

scripts/
  build_evaluation_fixture.py   generate benchmark from seed
  evaluate_workflow.py          run and score all four candidates
  validate_evidence.py          verify claims ledger and privacy rules
  benchmark_mcp.py              official MCP stdio latency benchmark
  verify_neo4j.py               live graph integration check
  compile_generated.py          ECJ compile gate
  seed_graph.py                 materialise fixture into Neo4j

tests/
  test_generation_loop.py       generation + validation unit tests
  test_graph_store.py           Neo4j adapter unit tests
  test_mcp_protocol.py          official MCP protocol conformance
  test_evaluation.py            evaluation harness tests
  test_evidence.py              claims ledger integrity tests
  test_neo4j_live.py            opt-in live graph tests (NEO4J_* env required)

docs/
  ARCHITECTURE.md        component design and data flow
  POLICY_CARD.md         candidate selection details
  DATA_CARD.md           fixture provenance and license
  MCP_INTEGRATION.md     client configuration guide
  DEPLOYMENT.md          Docker and container notes

templates/               MCP prompt templates for VS Code Copilot
examples/                sample project preflight scanner