The Problem

Developers need an automated way to understand, navigate, and repair large, heterogeneous codebases. Manual inspection is slow and error‑prone, especially when the code spans many languages and integrates external services (GitHub, Neo4j, LLM APIs).

What This Does

Prometheus builds a knowledge graph of a repository’s files, AST nodes, and textual artefacts, then runs reasoning agents (LLM‑driven sub‑graphs) to answer or fix GitHub issues.

  • Core graph logic lives in prometheus/graph/knowledge_graph.py and the supporting types in prometheus/graph/graph_types.py.
  • Docker orchestration (Dockerfile, docker-compose.yml) provides a Neo4j instance and a Python service container.
  • The FastAPI API (prometheus/app/api/main.py, routers under prometheus/app/api/routes/) exposes endpoints for repository cloning, issue retrieval, and LLM‑based patch generation.

How It Is Wired

Startup – Execution begins in prometheus/app/main.py (lifespan function). It creates a FastAPI app, registers the JWT middleware (prometheus/app/middlewares/jwt_middleware.py), and includes all route modules (/auth, /github, /issue, /repository, /user).

Request flow (example: POST /issue/solve)

  1. JWT middleware validates the bearer token (decode_token → jwt.decode).
  2. The route handler in prometheus/app/api/routes/issue.py calls IssueService (prometheus/app/services/issue_service.py).
  3. IssueService invokes KnowledgeGraphService (prometheus/app/services/knowledge_graph_service.py), which in turn calls KnowledgeGraphHandler (prometheus/neo4j/knowledge_graph_handler.py) to read/write Neo4j nodes.
  4. For a new GitHub issue, IssueService uses GitRepository (prometheus/git/git_repository.py) to clone the repo, then FileGraphBuilder (prometheus/graph/file_graph_builder.py) to populate the graph.
  5. LLM interaction is performed by LLMService (prometheus/app/services/llm_service.py), which constructs a FakeListChatWithToolsModel (used in tests) and invokes the tool‑enabled chain (__call__ -> invoke).

External touch points –

  • Network: GitRepository → client.get (GitHub API) and LLMService → external LLM endpoints.
  • Database: KnowledgeGraphHandler writes nodes/edges to Neo4j (≈20 functions).
  • Filesystem: FileGraphBuilder, GitRepository, and various file_operation helpers read/write source files (≈26 functions).

Blast‑radius hubs – knowledge_graph.py is imported by 54 modules, docker/base_container.py by 47, and git/git_repository.py by 42. Changes in these files propagate widely, so they should remain stable and well‑tested.

How To Use It

# 1. Clone the repo
git clone https://github.com/moses-y/Prometheus
cd Prometheus

# 2. Build and start containers
docker compose up --build -d   # uses Dockerfile and docker-compose.yml

# 3. Provide runtime config (copy the example)
cp example.env .env           # edit .env to add GITHUB_TOKEN, NE04J credentials, LLM keys

# 4. Run the API (inside the container or locally)
uvicorn prometheus.app.main:app --host 0.0.0.0 --port 8000

For ad‑hoc debugging of a single issue, the script prometheus/script/github_issue_debug.py can be executed directly:

python -m prometheus.script.github_issue_debug <issue_number>

The script follows the path main → process_issue → get_github_issue (network call) → graph construction → LLM reasoning.

Real‑World Use

A CI system detects a new GitHub issue, posts its ID to /issue/solve. The service clones the repo, builds a knowledge graph, runs the “bug‑fix verification” sub‑graph, and returns a suggested patch. The patch can be auto‑applied via the /repository/create_branch_and_push endpoint, closing the loop without human intervention.

Code Health & Issues

  • High – Pin GitHub Actions to commit SHAs (.github/workflows/*).
  • High – Add a lockfile (pyproject.toml → generate uv.lock or poetry.lock).
  • High – Remove privileged mode & host networking (docker-compose.yml).
  • Medium – Declare least‑privilege GITHUB_TOKEN permissions (ruff_check.yml).
  • Medium – Enable Dependabot/renovate for automated updates.
  • Medium – Pin base Docker image by digest (Dockerfile).
  • Medium – Add a dependency‑vulnerability scan step to CI.
  • Medium – Use persist-credentials: false on checkout (pytest_and_coverage.yml).
  • Medium – Run container as non‑root (Dockerfile).
  • Low – Set explicit timeout-minutes on workflow jobs.

Static analysis also flagged:

  • Deep nesting (max indent 7) in knowledge_graph.py, base_container.py, graph_traversal.py.
  • Hub modules with >50 dependents (see above).
  • Repeated 6‑line code blocks across many files – extract to shared helpers.
  • File opened without a context manager in file_graph_builder.py.
  • Broad except: clauses in script/github_issue_debug.py.

No critical findings were reported.

The Bottom Line

Prometheus delivers a full pipeline—from repo ingestion to LLM‑driven issue resolution—wrapped in a Docker‑composeable FastAPI service. The architecture is clear but hinges on several high‑centrality modules that need careful stewardship. Security hardening (action pinning, lockfile, container privileges) is required before production use. Suitable for teams ready to integrate automated code‑graph reasoning into their DevOps flow.