Skip to content
Merged
Show file tree
Hide file tree
Changes from 5 commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 44 additions & 8 deletions .cursor/agents/phase-orchestrator/agent.md
Original file line number Diff line number Diff line change
Expand Up @@ -76,14 +76,16 @@ Phase Start
│ Do NOT proceed to QA with unresolved critical issues
│
├─ 5. QA TEST (always before PR) ──────────────────────────
│ → Launch @qa-tester
│ → Launch @qa-tester — follow agent.md completely
│ Phase 1: environment validation only (Docker, Gitea Set A, DB, LLM)
│ Phase 2+: full Set B samples + edge cases
│ Record: score, pass/fail per sample
│ Phase 2+: full Set B (B1,B3–B8) + edge cases — NOT unit tests alone
│ If Docker/keys missing: run integration tests OR mark QA BLOCKED
│ Record: score, pass/fail per sample, or BLOCKED with blockers
│ IF failures:
│ → Launch @bug-fixer with QA report
│ → Re-launch @qa-tester
│ → Max 3 fix→retest loops; then stop and report blockers
│ IF BLOCKED: do NOT claim QA passed in PR
│
├─ 6. COMMIT + PUSH ───────────────────────────────────────
│ Stage all phase changes (including fix commits)
Expand Down Expand Up @@ -158,19 +160,51 @@ Compare against spec.md. Report: pass | warnings | critical with file:line refs.
@code-auditor → critical? → @bug-fixer → @code-auditor → (max 2 loops)
```

### 5. QA Test (always)
### 5. QA Test (always — mandatory for Phase 2+)

Launch `@qa-tester` via Task with phase-appropriate scope:

| Phase | QA scope |
|-------|----------|
| 1 | Environment validation only — Docker health, Gitea Set A, Postgres, LLM connectivity |
| 2+ | Full Set B (B1–B8) + edge cases (empty, hostile, malformed) |
| 2+ | **Full Set B (B1, B3–B8) + edge cases** — see `.cursor/agents/qa-tester/agent.md` |

#### QA is NOT optional and NOT satisfied by unit tests alone

**Unit tests (`pytest tests/unit`) do NOT count as Phase 2+ QA.** They validate isolated node logic only.

For Phase 2 and later, `@qa-tester` MUST attempt at least one of:

1. **Live Set B** — POST each sample to `http://localhost:8000/api/triage` against a running stack (Docker Compose preferred), **or**
2. **Integration tests** — `pytest tests/integration -q -v` with mocked LLM when live keys/Docker unavailable

If neither live Set B nor integration tests can run, QA status is **`BLOCKED`** — not "skipped", not "TODO", not "passed on unit tests only".

#### QA gate before PR

- Do **NOT** open a PR claiming "QA passed" unless Set B was **attempted** (live or integration).
- PR template `QA Results` must reflect actual status: `passed`, `partial`, `failed`, or **`BLOCKED`**.
- When `BLOCKED`, list blockers explicitly (missing `OPENAI_API_KEY`, `GITEA_TOKEN`, Docker down, postgres init failure, etc.).
- Record which samples ran and pass/fail per sample — never aggregate to a score without running them.

#### Environment prerequisites (qa-tester Phase 1)

Before Set B, verify:

```bash
docker-compose ps # postgres, gitea, triage-service Up
curl http://localhost:8000/health
curl http://localhost:3000/api/v1/repos/bugtracker/issues # Set A (4 issues)
python scripts/seed_gitea.py # if Set A missing
```

If `.env` missing: copy from `.env.example` and note required keys (`OPENAI_API_KEY`, `GITEA_TOKEN`).

**Fix loop (QA):**

```
@qa-tester → failures? → @bug-fixer → @qa-tester → (max 3 loops)
@qa-tester → BLOCKED? → stop pipeline; report blockers; do NOT mark QA passed
```

After 3 failed loops: stop pipeline, report blockers, do **not** create PR with known critical failures unless user overrides.
Expand Down Expand Up @@ -208,8 +242,9 @@ Create PR with `gh pr create`:
- **Critical issues fixed:** [count or N/A]

## QA Results
- **Mode:** [environment-only | full Set B]
- **Score:** [X/Y samples passed]
- **Mode:** [environment-only | full Set B live | integration (mocked LLM) | **BLOCKED**]
- **Score:** [X/7 Set B samples passed — only if attempted]
- **Blockers:** [missing keys, Docker down, postgres init failure, etc. — or none]
- **Failures:** [list or none]
- **Fix loops used:** [0-3]

Expand Down Expand Up @@ -282,6 +317,7 @@ Then update `WORKFLOW.md` phase checklist (mark phase complete). Commit checklis
| Implementation blocked (missing env, API key) | Stop; list what user must provide |
| Auditor critical after 2 fix loops | Stop before PR; report unresolved issues |
| QA fails after 3 fix loops | Stop before PR OR create draft PR with failures documented — prefer stop |
| QA **BLOCKED** (no keys/Docker/integration) | Stop before PR; status **BLOCKED** in report — never "QA passed" |
| `gh` not authenticated | Report; give manual PR URL steps |
| Phase already has open PR | Report existing PR; ask merge or continue fixes |

Expand All @@ -293,7 +329,7 @@ Then update `WORKFLOW.md` phase checklist (mark phase complete). Commit checklis
- [ ] Implementation uses langgraph-bug-triage skill
- [ ] spec-architect run OR skipped with reason
- [ ] code-auditor run — result recorded
- [ ] qa-tester run — result recorded
- [ ] qa-tester run — result recorded (**BLOCKED** if Set B not attempted for Phase 2+)
- [ ] Fix loops within limits
- [ ] Branch pushed
- [ ] PR created with full template
Expand Down
2 changes: 2 additions & 0 deletions requirements.txt
Original file line number Diff line number Diff line change
Expand Up @@ -11,9 +11,11 @@ fastapi>=0.115.0
uvicorn[standard]>=0.30.0

# Database & PostgreSQL
psycopg[binary,pool]>=3.1.0
psycopg2-binary>=2.9.9
asyncpg>=0.29.0
sqlalchemy>=2.0.0
langgraph-checkpoint-postgres>=2.0.0

# HTTP Client
httpx>=0.27.0
Expand Down
7 changes: 3 additions & 4 deletions scripts/init.sql
Original file line number Diff line number Diff line change
Expand Up @@ -18,17 +18,16 @@ CREATE TABLE IF NOT EXISTS issue_embeddings (
issue_id INTEGER PRIMARY KEY,
title TEXT NOT NULL,
description TEXT NOT NULL,
embedding vector(3072), -- text-embedding-3-large dimensions
embedding vector(1536), -- text-embedding-3-large truncated (ivfflat/hnsw max 2000 dims)
stacktrace_hash TEXT,
created_at TIMESTAMP DEFAULT NOW(),
updated_at TIMESTAMP DEFAULT NOW()
);

-- Create index for fast similarity search
-- Create index for fast similarity search (HNSW supports up to 2000 dims)
CREATE INDEX IF NOT EXISTS issue_embeddings_embedding_idx
ON issue_embeddings
USING ivfflat (embedding vector_cosine_ops)
WITH (lists = 100);
USING hnsw (embedding vector_cosine_ops);
Comment on lines +21 to +30

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win

Add an upgrade migration for existing databases.

CREATE TABLE IF NOT EXISTS leaves an existing vector(3072) column unchanged, so the newly configured 1536-dimensional embeddings will fail to persist after upgrade. The existing same-named IVFFlat index also will not be replaced by this HNSW definition. Add a versioned migration that re-embeds/backfills existing rows and replaces the index.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@scripts/init.sql` around lines 21 - 30, Add a versioned upgrade migration for
existing issue_embeddings tables that converts the embedding column from 3072 to
1536 dimensions, re-embeds or backfills all existing rows with the new
dimension, and replaces the existing same-named IVFFlat index with the HNSW
cosine index. Keep fresh-database initialization unchanged while ensuring the
migration is safe to rerun.


-- Create index for stacktrace hash lookup
CREATE INDEX IF NOT EXISTS issue_embeddings_stacktrace_hash_idx
Expand Down
69 changes: 41 additions & 28 deletions scripts/test_triage.py
Original file line number Diff line number Diff line change
@@ -1,55 +1,68 @@
#!/usr/bin/env python3
"""
CLI test harness for triage service
Allows testing triage from command line
CLI test harness for triage service.
Runs the LangGraph workflow locally with an in-memory checkpointer.
Requires OPENAI_API_KEY (and optionally GITEA_* for issue creation).
"""

import asyncio
import sys
import uuid
from pathlib import Path

# Add src to path
sys.path.insert(0, str(Path(__file__).parent.parent))

from langgraph.checkpoint.memory import MemorySaver

from src.graph.workflow import build_graph
from src.config import settings
from src.graph.state import create_initial_state
from src.utils.logging import setup_logging, logger


async def test_triage(report: str):
"""
Test triage workflow with a bug report

Args:
report: Bug report text
"""
async def test_triage(report: str) -> dict:
"""Run triage workflow with a bug report and print results."""
setup_logging()

logger.info("test_triage_start", report_length=len(report))

# TODO: Initialize checkpointer and compile graph
# For now, just log

print(f"\n{'='*60}")

thread_id = str(uuid.uuid4())
logger.info("test_triage_start", report_length=len(report), thread_id=thread_id)

graph = build_graph().compile(checkpointer=MemorySaver())
initial_state = create_initial_state(bug_report_text=report, thread_id=thread_id)
config = {
"configurable": {"thread_id": thread_id},
"recursion_limit": 50,
}

result = await graph.ainvoke(initial_state, config)

print(f"\n{'=' * 60}")
print("Bug Report Triage Test")
print(f"{'='*60}\n")
print(f"Input: {report[:100]}...")
print("\n⚠️ Workflow not yet implemented")
print("\nNext steps:")
print("1. Implement graph nodes (preprocess, risk_check, etc.)")
print("2. Wire up LangGraph workflow")
print("3. Connect to LLM services")
print(f"\n{'='*60}\n")
print(f"{'=' * 60}\n")
print(f"Thread ID: {thread_id}")
print(f"Title: {result.get('title', 'N/A')}")
print(f"Severity: {result.get('severity', 'N/A')}")
print(f"Components: {result.get('components', [])}")
print(f"Confidence: {result.get('confidence', 0.0):.2f}")
print(f"Needs human review: {result.get('needs_human_review', False)}")
print(f"Is duplicate: {result.get('is_duplicate', False)}")
if result.get("gitea_issue_url"):
print(f"Issue URL: {result['gitea_issue_url']}")
if result.get("processing_warnings"):
print(f"Warnings: {result['processing_warnings']}")
print(f"\n{'=' * 60}\n")

return result


def main():
"""Main CLI entry point"""
"""Main CLI entry point."""
if len(sys.argv) < 2:
print("Usage: python scripts/test_triage.py 'bug report text'")
print("\nExample:")
print(' python scripts/test_triage.py "Login button not working"')
print("\nRequires OPENAI_API_KEY in environment or .env file.")
sys.exit(1)

report = sys.argv[1]
asyncio.run(test_triage(report))

Expand Down
12 changes: 7 additions & 5 deletions src/config.py
Original file line number Diff line number Diff line change
Expand Up @@ -3,11 +3,16 @@
Loads settings from environment variables
"""

from pydantic_settings import BaseSettings
from pydantic_settings import BaseSettings, SettingsConfigDict
from typing import Optional


class Settings(BaseSettings):
model_config = SettingsConfigDict(
env_file=".env",
case_sensitive=False,
extra="ignore",
)
"""Application configuration loaded from environment"""

# Database
Expand Down Expand Up @@ -35,6 +40,7 @@ class Settings(BaseSettings):
fast_model: str = "gpt-4o-mini"
premium_model: str = "gpt-4o"
embedding_model: str = "text-embedding-3-large"
embedding_dimensions: int = 1536

# Thresholds
confidence_threshold: float = 0.70
Expand All @@ -43,10 +49,6 @@ class Settings(BaseSettings):

# Retry limits
max_retries: int = 3

class Config:
env_file = ".env"
case_sensitive = False


# Global settings instance
Expand Down
36 changes: 36 additions & 0 deletions src/graph/checkpointer.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
"""
PostgresSaver checkpointer setup for production workflow persistence
"""

from contextlib import AbstractContextManager
from typing import Optional

from langgraph.checkpoint.postgres import PostgresSaver

from src.config import settings
from src.utils.logging import logger

_checkpointer_ctx: Optional[AbstractContextManager[PostgresSaver]] = None
_checkpointer: Optional[PostgresSaver] = None


def setup_checkpointer() -> PostgresSaver:
"""Create and initialize PostgresSaver with connection string from settings."""
global _checkpointer_ctx, _checkpointer

_checkpointer_ctx = PostgresSaver.from_conn_string(settings.database_url)
_checkpointer = _checkpointer_ctx.__enter__()
_checkpointer.setup()
logger.info("checkpointer_ready", backend="postgres")
return _checkpointer
Comment on lines +17 to +25

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🩺 Stability & Availability | 🟠 Major | ⚡ Quick win

🧩 Analysis chain

🌐 Web query:

langgraph-checkpoint-postgres PostgresSaver ConnectionPool vs from_conn_string production

💡 Result:

For production environments, using a ConnectionPool is the recommended practice for PostgresSaver, as it provides robust resource management, handles concurrent requests, and prevents connection timeouts often encountered with long-running workflows [1][2][3]. The two methods differ primarily in their scope and production suitability: 1. PostgresSaver.from_conn_string(conn_string) This helper method is convenient for local development, testing, or quick prototyping [4][5]. Internally, it creates and manages its own connection, but it is generally not recommended for high-concurrency production deployments because it does not provide the sophisticated pooling needed to efficiently handle multiple persistent connections [2][6]. 2. PostgresSaver(pool) with ConnectionPool This is the standard approach for production. By passing a psycopg_pool.ConnectionPool instance to the PostgresSaver, you gain control over critical connection parameters such as minimum and maximum pool size, connection lifetime, and idle timeouts [7][1][8]. When implementing ConnectionPool in production: - Ensure autocommit=True and row_factory=dict_row are configured in the pool's kwargs to satisfy PostgresSaver requirements [7][9][10]. - The.setup method must be called once (often via CI/CD or a migration script, not during every application startup) to initialize the necessary database tables [3]. - Avoid using pipeline mode with a ConnectionPool, as it is designed for use only with a single dedicated connection [11][1]. Example Production Configuration: from psycopg.rows import dict_row from psycopg_pool import ConnectionPool from langgraph.checkpoint.postgres import PostgresSaver pool = ConnectionPool( conn_string, min_size=2, max_size=10, max_idle=300.0, max_lifetime=3600.0, kwargs={ "autocommit": True, "row_factory": dict_row, "prepare_threshold": 0 }) checkpointer = PostgresSaver(pool) # checkpointer.setup # Run once as a migration, not in app runtime[3] graph = builder.compile(checkpointer=checkpointer)

Citations:


🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "Files:"
git ls-files | rg '(^|/)(checkpointer\.py|main\.py|pyproject\.toml|requirements|poetry\.lock|uv\.lock)$' || true

echo
echo "checkpointer.py:"
cat -n src/graph/checkpointer.py

echo
echo "main.py relevant checkpointer usages:"
rg -n "_checkpointer|checkpointer|triage|lifespan|PostgresSaver|setup_checkpointer|close_checkpointer" src/main.py || true

echo
echo "Relevant graph/build lines in main.py:"
sed -n '1,240p' src/main.py | cat -n

echo
echo "Dependency declarations mentioning langgraph/psycopg:"
rg -n 'langgraph|postgres|psycopg|psycopg_pool' pyproject.toml poetry.lock uv.lock requirements*.txt setup.py setup.cfg 2>/dev/null || true

Repository: IWill29/bug-triage-langgraph

Length of output: 8242


Use a pool-backed PostgresSaver for concurrent requests

PostgresSaver.from_conn_string creates a saver backed by a single psycopg connection, while this FastAPI app compiles one graph with that checkpointer and each /api/triage request invokes it concurrently. Move to a ConnectionPool-backed saver instead.

♻️ Sketch: pool-backed checkpointer
-from contextlib import AbstractContextManager
-from typing import Optional
-
+from psycopg_pool import ConnectionPool
+from psycopg.rows import dict_row
+from typing import Optional
+
 from langgraph.checkpoint.postgres import PostgresSaver
 from src.config import settings
 from src.utils.logging import logger
 
 _checkpointer_ctx: Optional[AbstractContextManager[PostgresSaver]] = None
 _checkpointer: Optional[PostgresSaver] = None
 
 def setup_checkpointer() -> PostgresSaver:
     """Create and initialize PostgresSaver with connection string from settings."""
     global _checkpointer_ctx, _checkpointer
+    _pool = ConnectionPool(
+        conninfo=settings.database_url,
+        min_size=2,
+        max_size=16,
+        kwargs={"autocommit": True, "row_factory": dict_row, "prepare_threshold": 0},
+    )
+    _checkpointer = PostgresSaver(_pool)
+    _checkpointer.setup()
+    logger.info("checkpointer_ready", backend="postgres")
+    return _checkpointer
 
-def setup_checkpointer() -> PostgresSaver:
-    """Create and initialize PostgresSaver with connection string from settings."""
-    global _checkpointer_ctx, _checkpointer
-
-    _checkpointer_ctx = PostgresSaver.from_conn_string(settings.database_url)
-    _checkpointer = _checkpointer_ctx.__enter__()
-    _checkpointer.setup()
-    logger.info("checkpointer_ready", backend="postgres")
-    return _checkpointer
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/graph/checkpointer.py` around lines 17 - 25, Update setup_checkpointer to
create a psycopg ConnectionPool configured from settings.database_url, then
construct and initialize PostgresSaver with that pool instead of using
PostgresSaver.from_conn_string. Preserve the existing global context/instance
assignment, setup call, readiness log, and return behavior, while ensuring the
pool lifecycle is managed by the existing checkpointer context.



def close_checkpointer() -> None:
"""Release PostgresSaver connection on shutdown."""
global _checkpointer_ctx, _checkpointer

if _checkpointer_ctx is not None:
_checkpointer_ctx.__exit__(None, None, None)
_checkpointer_ctx = None
_checkpointer = None
logger.info("checkpointer_closed")
32 changes: 32 additions & 0 deletions src/graph/nodes/__init__.py
Original file line number Diff line number Diff line change
@@ -1,3 +1,35 @@
"""
Graph nodes - Individual workflow step implementations
"""

from src.graph.nodes.preprocess import preprocess_node
from src.graph.nodes.risk_check import risk_check_node
from src.graph.nodes.triage import (
fast_triage_node,
premium_retry_node,
route_confidence,
)
from src.graph.nodes.validate import validate_node
from src.graph.nodes.duplicate import duplicate_check_node
from src.graph.nodes.gitea import (
create_issue_node,
create_feature_node,
comment_duplicate_node,
human_review_node,
route_issue_creation,
)

__all__ = [
"preprocess_node",
"risk_check_node",
"fast_triage_node",
"premium_retry_node",
"route_confidence",
"validate_node",
"duplicate_check_node",
"create_issue_node",
"create_feature_node",
"comment_duplicate_node",
"human_review_node",
"route_issue_creation",
]
Loading