Skip to content

Commit 38628dd

Browse files
darestackdarestack
committed
Identity: Unify Behavioral and GitOps personas in project core
1 parent 2f11e1e commit 38628dd

3 files changed

Lines changed: 75 additions & 114 deletions

File tree

‎README.md‎

Lines changed: 37 additions & 114 deletions
Original file line numberDiff line numberDiff line change
@@ -1,142 +1,65 @@
1-
# CommitGuard AI: The Accountability Specialist 🛡️
1+
# CommitGuard AI: The Autonomous Accountability Platform 🛡️
22

33
![CommitGuard AI Hero](docs/assets/hero.jpg)
44

5-
> **Automation Specialist Angle:** Automating the hardest part of human management using sentiment-aware AI agents.
5+
> **"One Engine. Two Worlds. Total Accountability."**
66
77
[**Full Documentation 📚**](https://daretechie.github.io/CommitGuard-AI/)
88

9+
---
910

11+
## 🎭 Dual-Persona Versatility
1012

11-
**"CommitGuard AI provide 'Accountability as a Service.' CommitGuard predicts when a team member is likely to fail *before* the deadline and intervenes with the right behavioral tone to ensure delivery."**
12-
13-
## 🆘 The Problem
14-
In modern distributed teams, the **"Slack Stall"** is the #1 drain on project velocity. Project Managers are overwhelmed by vague promises like *"I'll get to it soon,"* which are often forgotten, leading to missed sprints and "bad guy" escalations.
15-
16-
## ✅ The Solution: CommitGuard AI
17-
CommitGuard AI is a standalone, agentic service designed to monitor and enforce professional commitments. It doesn't just "track tasks"; it acts as a proactive collaborator that:
18-
1. **Extracts Vague Promises**: Automatically parses Slack threads to create structured commitment records.
19-
2. **Predicts Failure**: Uses behavioral sentiment to flag burnout or deflection *before* the deadline passes.
20-
3. **Automates Calibration**: Adjusts its tone—Supportive for burnout, Firm for repeat offenders—saving the PM from having to chase updates.
21-
22-
23-
## 🚀 Key Features
24-
- **Deterministic AI Agents**: Built with `FastAPI`, `instructor`, and `Pydantic` for structured, reliable JSON outputs.
25-
- **Behavioral Analysis**:
26-
- `ExcuseDetector`: Classifies reasons for commitment failure (Legitimate vs. Deflection vs. Burnout).
27-
- `RiskAssessor`: Quantifies the probability of failure based on historical context.
28-
- `ToneAdapter`: Dynamically shifts empathy levels (Supportive → Confrontational) based on performance.
29-
- **Asynchronous Orchestration**:
30-
- **Task Queue**: Uses `ARQ` + `Redis` to offload LLM latency from the main API thread.
31-
- **Accountability Scheduler**: Uses `APScheduler` for precision, time-sensitive follow-up actions.
32-
- **Elite Modular Architecture**: Pluggable **LLM Provider Factory** supporting OpenAI, Claude (Anthropic), and hermetic mock providers.
33-
- **Identity Attribution**: Specialized logic to automatically extract commitment "Owners" from raw thread text.
34-
- **Production Observability**: Structured JSON logging (`structlog`) and metrics instrumentation (`Prometheus`).
35-
- **Resilient Test Suite**: Comprehensive `pytest` suite with **Mock Providers**, ensuring 100% reliability in offline environments.
36-
37-
38-
## 🏗️ Architecture: Asynchronous Agentic Worker Pattern
39-
40-
In production high-volume environments, we never block the user request for AI reasoning. CommitGuard AI uses an **event-driven architecture** where the API acts as a gateway and background workers handle the "Brain" logic.
41-
42-
```mermaid
43-
graph TD
44-
User[Client Application] -->|POST /evaluate| API[FastAPI Gateway]
45-
API -->|Enqueue Job| Redis[Redis Queue]
46-
47-
subgraph "Worker Process"
48-
Redis --> Worker[ARQ Worker]
49-
Worker --> Brain[CommitGuard Brain]
50-
Brain --> Excuse[Excuse Detector]
51-
Brain --> Risk[Risk Scorer]
52-
Brain --> Burnout[Burnout Guard]
53-
Brain --> Tone[Tone Adapter]
54-
55-
Tone --> Decision[Action Decision]
56-
Decision --> Scheduler[APScheduler]
57-
end
58-
59-
Scheduler -->|Trigger Follow-up| User
60-
```
13+
CommitGuard AI is a multi-agent system designed for high-stakes enforcement. It adapts its identity based on the operational environment:
6114

62-
### Technical Significance:
63-
1. **Vendor Agnostic**: Swap LLM providers (from OpenAI to Claude or local Llama) in 2 seconds via configuration.
64-
2. **Deterministic Outputs**: Every agent uses Pydantic-enforced schemas to guarantee reliable downstream processing.
65-
3. **Latency Decoupling**: The user receives a 202 Accepted response instantly, while the asynchronous worker handles reasoning out-of-band.
66-
4. **Identity Attribution**: The agent doesn't just extract tasks; it identifies the specific human owner responsible for the commitment.
15+
### 1. The Behavioral Accountability Agent (Management)
16+
**Headline:** *"Autonomous AI Agents for High-Stakes Accountability & Performance Enforcement"*
17+
- **Problem:** Remote teams struggle with "commitment drift" and excuse-making.
18+
- **Solution:** Proactively monitor chat promises.
19+
- **Outcome:** Support burnout signals early; confront repeat deflection firmly.
6720

68-
## 💬 Slack Integration Guide
21+
### 2. The GitOps Accountability Engine (Engineering)
22+
**Headline:** *"AI-Driven GitOps Accountability: Guaranteeing Commitment Follow-Through"*
23+
- **Problem:** Small technical promises in commits/PRs (e.g., *"I'll fix this later"*) vanish into the noise.
24+
- **Solution:** NLP-driven monitoring of source code level commitments.
25+
- **Outcome:** 100% visibility into "soft commitments" made during the dev cycle.
6926

70-
### How to use it:
71-
CommitGuard AI acts as a **Proactive Accountability Partner** in your workspace.
27+
---
7228

73-
1. **Setup**: The manager creates an [Incoming Webhook](https://api.slack.com/messaging/webhooks) for your project channel.
74-
2. **Configuration**: Add the URL to your `.env`:
75-
```bash
76-
SLACK_WEBHOOK_URL="https://hooks.slack.com/services/..."
77-
```
78-
3. **Automated Intervention**:
79-
- When the developer updates the system with an excuse (via the `/evaluate` endpoint), the agent analyzes their history and sentiment.
80-
- If the risk is **High** or **Critical**, CommitGuard will autonomously post a formatted "Burnout Alert" or "Accountability Warning" to the Slack channel.
81-
- **Result**: You save 1-2 hours of manual follow-up time every day.
29+
## 🏗️ The Three-Stage Autonomous Pipeline
30+
Every commitment—whether from Slack or a Git Commit—passes through a deterministic reasoning loop:
8231

32+
1. **Excuse Detection (`ExcuseDetector`)**: Classifies sentiment (Legitimate vs. Deflection vs. Burnout).
33+
2. **Predictive Risk Assessment (`RiskScorer`)**: Quantifies failure probability based on historical reliability.
34+
3. **Adaptive Pressure (`ToneAdapter`)**: Selects the psychological tone (Supportive → Firm → Confrontational) to ensure delivery.
8335

36+
---
8437

85-
## 💡 API Usage Examples
38+
## 🛠️ Core Tech Stack
39+
- **Framework**: FastAPI (Python 3.12+)
40+
- **LLM Orchestration**: Instructor + Pydantic (Deterministic JSON)
41+
- **Infrastructure**: PostgreSQL + Redis + ARQ
42+
- **Observability**: Prometheus + Structlog
8643

87-
### 1. Ingest a Raw Slack Promise
88-
Automatically extracts who, what, and when from natural language.
44+
---
45+
46+
## 🚀 API Showcase
47+
### Raw Extraction (Slack/Commit/PR)
8948
```bash
9049
curl -X 'POST' \
91-
'http://localhost:8000/ingest/raw?user_id=john_dev&raw_text=I%20promise%20to%20fix%20the%20CSS%20bugs%20by%20tomorrow%20evening' \
92-
-H 'accept: application/json'
50+
'http://localhost:8000/ingest/raw?user_id=dev_alpha&raw_text=Fixing%20auth%20logic.%20I%20promise%20to%20refactor%20the%20DB%20connector%20by%20Friday'
9351
```
9452

95-
### 2. Evaluate a User Check-in
96-
Triggers the agentic reasoning pipeline (Excuse analysis -> Risk Assessment -> Burnout Detection -> Notification).
53+
### Behavioral Evaluation
9754
```bash
9855
curl -X 'POST' \
9956
'http://localhost:8000/evaluate' \
100-
-H 'accept: application/json' \
101-
-H 'Content-Type: application/json' \
10257
-d '{
103-
"user_id": "john_dev",
104-
"commitment": "fix the CSS bugs",
105-
"check_in": "I am almost there but honestly I am extremely tired and might need more time"
58+
"user_id": "dev_alpha",
59+
"commitment": "refactor the DB connector",
60+
"check_in": "Spent all night on it, feeling pretty drained"
10661
}'
10762
```
10863

10964
---
110-
111-
## 🛠️ Tech Stack
112-
113-
- **Framework**: FastAPI (Python 3.12+)
114-
- **LLM Orchestration**: Instructor + Pydantic
115-
- **Message Broker**: Redis
116-
- **Task Queue**: ARQ
117-
- **Job Scheduling**: APScheduler
118-
- **Logging**: Structlog
119-
- **Metrics**: Prometheus
120-
121-
## 🚦 Getting Started
122-
123-
### 1. Local Development (Poetry)
124-
```bash
125-
# Start Infrastructure
126-
docker-compose up -d
127-
128-
# Start API
129-
poetry run uvicorn src.main:app --reload
130-
131-
# Start Worker
132-
poetry run arq src.worker.WorkerSettings
133-
```
134-
135-
### 2. Production (Docker)
136-
```bash
137-
docker-compose up --build
138-
```
139-
140-
---
141-
142-
*Built by [daretechie](https://github.com/daretechie) as a demonstration of high-ticket AI Agent Architecture.*
65+
*Built for High-Performance Teams and Elite Portfolios.*

‎docs/overviews/personas.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# Behavioral vs. GitOps Accountability 🎭
2+
3+
CommitGuard AI is built as a **Dual-Mode Platform**. While the internal engine (the "Brain") is a single set of standardized agents, it can be applied to two very different high-value problems.
4+
5+
---
6+
7+
## 1. Behavioral Accountability (Chat & Management)
8+
**Target**: Project Managers, CEOs, and Distributed Team Leads.
9+
**Focus**: The "Human Layer."
10+
11+
In this mode, CommitGuard monitors natural language communication (Slack, Discord, Teams).
12+
- **The Problem**: Users make vague, "soft" promises that are easy to forget.
13+
- **The Intervention**: The agent detects **Burnout** or **Deflection** in follow-up chat messages.
14+
- **Example**: *"I'm really tired, the bugs are harder than I thought, might miss it."* -> **Tone: Supportive.**
15+
16+
---
17+
18+
## 2. GitOps Accountability (Code & CI/CD)
19+
**Target**: CTOs, Tech Leads, and Engineering Managers.
20+
**Focus**: The "Code Layer."
21+
22+
In this mode, CommitGuard monitors commit messages, PR descriptions, and code comments.
23+
- **The Problem**: Developers leave "TODOs" or promises like *"I'll fix this in the next PR"* which accumulate into brittle technical debt.
24+
- **The Intervention**: The agent extracts these promises from the source level and maps them to the developer's Git identity.
25+
- **Example**: *"Fixing auth logic. I'll refactor the DB connector by Friday."* -> **Commitment Extracted.**
26+
27+
---
28+
29+
## 🏗️ The Unified Engine
30+
Both modes leverage the same high-tier infrastructure:
31+
1. **Ingestion API**: Generic endpoints that handle any unstructured text.
32+
2. **Specialized Agents**: `ExcuseDetector`, `RiskScorer`, and `ToneAdapter`.
33+
3. **Persistence**: SQLModel saves every interaction to track historical reliability over time.
34+
4. **Notifications**: Real-world Slack Webhooks with `@mentions`.
35+
36+
**By mastering both modes, CommitGuard AI provides an end-to-end "Accountability as a Service" solution for modern engineering organizations.**

‎mkdocs.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,9 @@ nav:
5151
- Introduction: index.md
5252
- Operational Overviews:
5353
- The Accountability Specialist: overviews/concept.md
54+
- Behavioral vs GitOps Personas: overviews/personas.md
5455
- Agentic Reasoning Logic: overviews/agents.md
56+
5557
- Usage Guides:
5658
- Quick Start: guides/quickstart.md
5759
- Slack Integration: guides/slack.md

0 commit comments

Comments
 (0)