Clarify CommitVigil scope

Author: darestack

README.md

@@ -3,96 +3,102 @@
 [![CI](https://github.com/daretechie/CommitVigil/actions/workflows/ci.yml/badge.svg)](https://github.com/daretechie/CommitVigil/actions/workflows/ci.yml)
 ![Python](https://img.shields.io/badge/python-3.12%2B-blue)
 
-> GitHub webhook listener that monitors commits and pull requests for risky patterns,
-> evaluates developer commitments against actual delivery, and sends Slack alerts on violations.
+> FastAPI lab for extracting commitments from chat and Git commit text, with Slack/reporting components, PostgreSQL, Redis, background workers, and Prometheus metrics.
 
----
+## Problem
 
-## What It Does
+Teams often make commitments in chat, commit messages, or review comments, but those commitments are hard to track later. This project explores a small service that extracts structured commitment records and connects them to reporting and feedback workflows.
 
-CommitVigil sits between your GitHub repository and your team's Slack channel. It:
+This is an application/backend lab, not a lead DevOps portfolio project.
 
-1. **Receives GitHub webhook events** — push, pull_request, commit comment
-2. **Scans for risky patterns**:
-   - Direct pushes to `main`/`master` without a PR
-   - Unusually large diffs (configurable threshold)
-   - Commit messages containing secret-like strings
-   - Soft commitments ("I'll fix this later", "TODO: refactor") tracked against follow-through
-3. **Scores and classifies** the event using structured LLM extraction (Instructor + Pydantic)
-4. **Sends a Slack alert** with the violation type, commit author, and diff link
+## Current Scope
 
----
+Implemented or represented in the repo:
 
-## Architecture
+- FastAPI app with versioned API routing.
+- `/ingest/raw` endpoint for extracting commitments from raw text.
+- `/ingest/git` endpoint for extracting commitments from Git commit messages.
+- API-key protection and request rate limiting.
+- PostgreSQL, Redis, worker, and Prometheus services in Docker Compose.
+- Structured logging and basic health checks.
+- Tests for API, worker, database, Slack, reports, safety, and performance paths.
 
-```
-GitHub Repository
-  └── Webhook (push / pull_request events)
-        └── CommitVigil API (FastAPI)
-              ├── Ingest: validates HMAC signature → queues job (ARQ + Redis)
-              ├── Worker: pattern scan → LLM evaluation → risk score
-              │     ├── Direct-push detector
-              │     ├── Large-diff detector (threshold: configurable)
-              │     └── Secret-pattern regex scan
-              └── Alert dispatcher → Slack Incoming Webhook
-```
+Not currently proven in this README:
+
+- GitHub webhook HMAC validation.
+- Direct-push detection.
+- Large-diff analysis from real GitHub payloads.
+- Production Slack alert screenshots.
+- End-to-end deployment evidence.
 
-**Async processing:** Events are acknowledged immediately (200 OK) and processed by an ARQ background worker — GitHub's 10-second timeout is never a concern.
+Those should be added before presenting this as a GitHub security or DevOps control.
 
----
+## Architecture
+
+```text
+Client / script
+  -> CommitVigil API (FastAPI)
+  -> ingestion endpoint
+  -> commitment extraction
+  -> database / reporting paths
+  -> optional Slack or report output
+
+Docker Compose
+  -> api
+  -> worker
+  -> redis
+  -> postgres
+  -> prometheus
+```
 
 ## Tech Stack
 
 | Layer | Technology |
 |---|---|
-| API | FastAPI (Python 3.12+) |
-| Background jobs | ARQ (async Redis queue) |
-| LLM extraction | Instructor + Pydantic |
-| Database | PostgreSQL |
-| Cache / queue | Redis |
-| Observability | Prometheus + Structlog |
-
----
+| API | FastAPI, Python 3.12 |
+| Background jobs | ARQ, Redis |
+| Database | PostgreSQL, SQLModel/Alembic |
+| Reporting / templates | Jinja2 |
+| Observability | Prometheus, structured logging |
+| Testing | pytest, pytest-asyncio, httpx |
 
 ## Quick Start
 
 ```bash
 git clone https://github.com/darestack/CommitVigil.git
 cd CommitVigil
-cp .env.example .env     # add GITHUB_WEBHOOK_SECRET and SLACK_WEBHOOK_URL
+cp .env.example .env
 docker compose up -d
 ```
 
-**Configure GitHub webhook:**
-1. Repo → Settings → Webhooks → Add webhook
-2. Payload URL: `https://your-domain/api/v1/ingest/raw`
-3. Content type: `application/json`
-4. Secret: the value from your `.env`
-5. Events: Push + Pull requests
-
----
-
-## Example Alert
+API:
 
-```
-⚠️  CommitVigil Alert
-Repo:    darestack/my-service
-Author:  daretechie
-Event:   Direct push to main (no PR)
-Commit:  a3f9c12 — "hotfix: temp disable auth check"
-Risk:    HIGH — bypassed code review + suspicious message pattern
-Link:    https://github.com/darestack/my-service/commit/a3f9c12
+```text
+http://localhost:8000
+http://localhost:8000/docs
+http://localhost:8000/health
 ```
 
----
+## Main Endpoints
 
-## Configuration
+| Endpoint | Purpose |
+|---|---|
+| `POST /api/v1/ingest/raw` | Extract a structured commitment from raw chat-style text |
+| `POST /api/v1/ingest/git` | Extract a structured commitment from a Git commit message |
+| `GET /health` | Check API, database, and Redis status |
+| `GET /metrics` | Prometheus metrics, protected by API key |
 
-| Variable | Purpose |
+## Evidence To Add
+
+| Evidence | Status |
 |---|---|
-| `GITHUB_WEBHOOK_SECRET` | HMAC secret for validating GitHub payloads |
-| `SLACK_WEBHOOK_URL` | Incoming webhook URL for Slack alerts |
-| `LARGE_DIFF_THRESHOLD` | Line count triggering large-diff alert (default: 500) |
-| `DATABASE_URL` | PostgreSQL connection string |
-| `REDIS_URL` | Redis connection string |
-| `GROQ_API_KEY` / `OPENAI_API_KEY` | LLM provider key |
+| CI run screenshot | Needed |
+| Example request and response | Needed |
+| Prometheus metrics screenshot | Needed |
+| Worker log showing async processing | Needed |
+| Slack/report output screenshot | Needed before alerting claims |
+| GitHub webhook fixture and HMAC test | Needed before webhook/security claims |
+
+## Portfolio Note
+
+This repo should stay unpinned until the README, product scope, and proof artifacts are tighter. If it is kept public, frame it as a backend/automation lab rather than a production DevOps security system.

pyproject.toml

@@ -1,7 +1,7 @@
 [tool.poetry]
 name = "commitvigil"
 version = "0.1.0"
-description = "CommitVigil is a standalone, AI-powered service designed to enforce human commitments and behavioral accountability."
+description = "FastAPI lab for extracting commitments from chat and Git commit text."
 license = "MIT"
 authors = ["daretechie <deeprince2020@gmail.com>"]
 readme = "README.md"
@@ -86,4 +86,3 @@ exclude = ["migrations/", "tests/"]
 [tool.bandit]
 exclude_dirs = ["tests", "migrations"]
 tests = ["B201", "B301"]
-

src/api/v1/ingestion.py

@@ -22,18 +22,18 @@ class GitCommitInbound(BaseModel):
 )
 async def ingest_raw_commitment(user_id: str, raw_text: str):
     """
-    Elite Feature: Extract structured commitment record from raw Slack/Discord text.
+    Extract a structured commitment record from raw chat text.
     """
     extractor = CommitmentExtractor()
 
     extracted = await extractor.parse_conversation(raw_text)
 
-    # Hash identity for Privacy-Preserving Logging
+    # Hash identity before logging.
     identity_hash = (
         hashlib.sha256(extracted.who.encode()).hexdigest()[:12] if extracted.who else "none"
     )
 
-    # Audit: In a full production system, we would persist this to a 'tasks' table.
+    # In a full workflow, this would be persisted to a tasks table.
     logger.info(
         "commitment_extracted",
         user_id=user_id,
@@ -55,7 +55,7 @@ async def ingest_raw_commitment(user_id: str, raw_text: str):
 )
 async def ingest_git_commitment(commit_data: GitCommitInbound):
     """
-    Advanced GitOps Feature: Extract commitments directly from Git Commit Messages.
+    Extract commitments from Git commit messages.
     """
     extractor = CommitmentExtractor()
     author_email = commit_data.author_email

src/main.py

@@ -52,7 +52,7 @@ async def dispatch(self, request: Request, call_next) -> Response:
 @asynccontextmanager
 async def lifespan(fastapi_app: FastAPI):  # noqa: ARG001
     """
-    Modern lifespan management for Enterprise FastAPI apps.
+    Lifespan management for the FastAPI app.
     Handles startup and shutdown logic.
     """
     logger.info("application_startup", status="initializing_resources")