Skip to content

Commit 480e15a

Browse files
darestackdarestack
committed
Docs: Initialize professional Material for MkDocs suite and automated deployment
1 parent 79b2557 commit 480e15a

8 files changed

Lines changed: 251 additions & 0 deletions

File tree

‎.github/workflows/docs.yml‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
name: docs
2+
on:
3+
push:
4+
branches:
5+
- main
6+
permissions:
7+
contents: write
8+
jobs:
9+
deploy:
10+
runs-on: ubuntu-latest
11+
steps:
12+
- uses: actions/checkout@v4
13+
- name: Configure Git Credentials
14+
run: |
15+
git config user.name github-actions[bot]
16+
git config user.email 41898282+github-actions[bot]@users.noreply.github.com
17+
- uses: actions/setup-python@v5
18+
with:
19+
python-version: 3.x
20+
- run: echo "cache_id=$(date --utc +%V)" >> $GITHUB_ENV
21+
- uses: actions/cache@v4
22+
with:
23+
key: mkdocs-material-${{ env.cache_id }}
24+
path: .cache
25+
restore-keys: |
26+
mkdocs-material-
27+
- run: pip install mkdocs-material mkdocstrings[python]
28+
- run: mkdocs gh-deploy --force

‎docs/guides/quickstart.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# Quick Start Guide ⚡
2+
3+
Get CommitGuard AI running in under 5 minutes.
4+
5+
## 🐳 Running with Docker (Recommended)
6+
The fastest way to spin up the full stack (API + Worker + Redis + Postgres):
7+
8+
```bash
9+
docker-compose up --build
10+
```
11+
12+
## 🏗️ Local Poetry Setup
13+
1. **Install dependencies**:
14+
```bash
15+
poetry install
16+
```
17+
2. **Configure Environment**:
18+
Create a `.env` file based on `.env.example`.
19+
3. **Run the API**:
20+
```bash
21+
poetry run uvicorn src.main:app --reload
22+
```
23+
4. **Run the Worker**:
24+
```bash
25+
poetry run arq src.worker.WorkerSettings
26+
```
27+
28+
---
29+
30+
## 🧪 Running the Test Suite
31+
Standardized tests are enforced with 90%+ coverage.
32+
```bash
33+
poetry run pytest
34+
```

‎docs/guides/slack.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# Slack Integration Guide 💬
2+
3+
Transform the agent into a visible collaborator by bridging it to your Slack workspace.
4+
5+
## 1. Webhook Setup
6+
To receive notifications, you need an **Incoming Webhook URL**:
7+
1. Go to [Slack API Apps](https://api.slack.com/apps).
8+
2. Create a new app (from scratch).
9+
3. Enable **Incoming Webhooks**.
10+
4. Add a new webhook to your channel and copy the URL.
11+
12+
## 2. Configuration
13+
Add the URL to your `.env`:
14+
```bash
15+
SLACK_WEBHOOK_URL="https://hooks.slack.com/services/T000.../B000.../XXXX..."
16+
```
17+
18+
## 3. User @Mentions (Identity Mapping)
19+
CommitGuard can ping users directly using their **Slack Member ID**.
20+
21+
### How to map a user:
22+
Call the configuration endpoint with the user's Slack ID (found in their Slack Profile -> More -> Copy Member ID):
23+
24+
```bash
25+
POST /users/config/slack?user_id=john_dev&slack_id=U12345678
26+
```
27+
28+
### The Result
29+
When an alert is triggered, Slack turns the ID into a real mention:
30+
> 🔔 **CommitGuard Alert for @John:** Checking in on commitment: fix the CSS bugs

‎docs/index.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# CommitGuard AI: The Accountability Specialist 🛡️
2+
3+
> **"I provide 'Accountability as a Service.' My agent predicts when a team member is likely to fail *before* the deadline and intervenes with the right behavioral tone to ensure delivery."**
4+
5+
## 🆘 The Problem
6+
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.
7+
8+
## ✅ The Solution
9+
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:
10+
11+
1. **Extracts Vague Promises**: Automatically parses Slack threads to create structured commitment records.
12+
2. **Predicts Failure**: Uses behavioral sentiment to flag burnout or deflection *before* the deadline passes.
13+
3. **Automates Calibration**: Adjusts its tone—Supportive for burnout, Firm for repeat offenders—saving the PM from having to chase updates.
14+
15+
---
16+
17+
## 🏗️ Architecture at a Glance
18+
CommitGuard AI is built on a **Decoupled Event-Driven Architecture**:
19+
- **FastAPI Entrypoint**: High-speed ingestion.
20+
- **Redis & ARQ**: Distributed background processing.
21+
- **The Brain**: Pluggable LLM reasoning loop.
22+
- **PostgreSQL**: Industrial-grade persistence.

‎docs/overviews/agents.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# Agentic Reasoning Logic 🧠
2+
3+
CommitGuard AI uses three distinct layers of reasoning to decide how to intervene.
4+
5+
## 1. Excuse Analysis (`ExcuseDetector`)
6+
The agent categorizes the check-in sentiment:
7+
- **Legitimate**: Family emergencies, personal health.
8+
- **Deflection**: "Too busy," "I forgot," "I'll do it later."
9+
- **Burnout Signal**: Linguistic markers of deep fatigue or loss of interest.
10+
11+
## 2. Predictive Risk Scoring (`RiskScorer`)
12+
The agent generates a score (0.0 - 1.0) based on:
13+
- The **Confidence** of the current check-in.
14+
- The **Historical Reliability** of the user (stored in PostgreSQL).
15+
- The **Category** of the excuse.
16+
17+
## 3. Tone Adaptation (`ToneAdapter`)
18+
The final decision is a personalized intervention:
19+
- **Tone: Supportive** - If risk is high but burnout is detected.
20+
- **Tone: Firm** - If risk is high and the user has a history of deflection.
21+
- **Tone: Neutral** - For standard updates.
22+
23+
---
24+
25+
### Example Decision
26+
> **Input**: *"I'm really tired, the bugs are harder than I thought, might miss it."*
27+
>
28+
> **Agent Decision**:
29+
> - **Category**: Burnout Signal
30+
> - **Risk**: High (0.85)
31+
> - **Tone**: Supportive
32+
> - **Action**: *"Hey @User, I'm detecting some burnout signs. Let's look at the scope together before the deadline."*

‎docs/overviews/concept.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# The Accountability Specialist Concept 🛰️
2+
3+
CommitGuard AI is designed around a single philosophical pillar: **Human accountability is the hardest thing to automate, so we built an agent that handles the emotional labor for you.**
4+
5+
## 🎯 The Portfolio Angle
6+
This project isn't just a "wrapper." It demonstrates:
7+
- **Agentic Workflows**: Decisions are not hardcoded if/else statements; they are reasoned by LLMs based on historical context.
8+
- **Stateful Intelligence**: The system "remembers" user behavior across sessions.
9+
- **Enterprise Hardening**: Built with industrial standards (PostgreSQL, Redis, Ruff, 90%+ Testing).
10+
11+
## 🛠️ Operational Workflow
12+
1. **Ingestion**: A manager pings an endpoint with raw Slack text.
13+
2. **extraction**: The agent identifies the human owner and the commitment details.
14+
3. **Monitoring**: The background worker schedules a "Heartbeat Check."
15+
4. **Intervention**: If the check-in sounds risky, the agent pings the user on Slack.

‎docs/reference/api.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# API Reference 📖
2+
3+
CommitGuard AI provides a clean RESTful interface for all operations.
4+
5+
## 📥 Commitment Ingestion
6+
7+
::: src.main.ingest_raw_commitment
8+
options:
9+
show_root_heading: true
10+
show_source: false
11+
12+
## 🚦 Accountability Evaluation
13+
14+
::: src.main.evaluate_commitment
15+
options:
16+
show_root_heading: true
17+
show_source: false
18+
19+
## ⚙️ User Configuration
20+
21+
::: src.main.map_slack_user
22+
options:
23+
show_root_heading: true
24+
show_source: false

‎mkdocs.yml‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
site_name: CommitGuard AI
2+
site_url: https://daretechie.github.io/CommitGuard-AI/
3+
site_description: The Accountability Specialist - Automating human management with sentiment-aware AI agents.
4+
site_author: daretechie
5+
6+
repo_name: daretechie/CommitGuard-AI
7+
repo_url: https://github.com/daretechie/CommitGuard-AI
8+
9+
theme:
10+
name: material
11+
palette:
12+
# Palette toggle for light mode
13+
- media: "(prefers-color-scheme: light)"
14+
scheme: default
15+
primary: teal
16+
accent: cyan
17+
toggle:
18+
icon: material/brightness-7
19+
name: Switch to dark mode
20+
21+
# Palette toggle for dark mode
22+
- media: "(prefers-color-scheme: dark)"
23+
scheme: slate
24+
primary: teal
25+
accent: cyan
26+
toggle:
27+
icon: material/brightness-4
28+
name: Switch to light mode
29+
features:
30+
- navigation.tabs
31+
- navigation.sections
32+
- navigation.expand
33+
- navigation.top
34+
- search.suggest
35+
- search.highlight
36+
- content.code.copy
37+
- content.code.annotate
38+
39+
markdown_extensions:
40+
- admonition
41+
- pymdownx.details
42+
- pymdownx.superfences
43+
- pymdownx.highlight:
44+
anchor_linenums: true
45+
- pymdownx.inlinehilite
46+
- pymdownx.snippets
47+
- pymdownx.tabbed:
48+
alternate_style: true
49+
50+
nav:
51+
- Introduction: index.md
52+
- Operational Overviews:
53+
- The Accountability Specialist: overviews/concept.md
54+
- Agentic Reasoning Logic: overviews/agents.md
55+
- Usage Guides:
56+
- Quick Start: guides/quickstart.md
57+
- Slack Integration: guides/slack.md
58+
- API Reference:
59+
- Endpoint Specs: reference/api.md
60+
61+
plugins:
62+
- search
63+
- mkdocstrings:
64+
handlers:
65+
python:
66+
paths: [src]

0 commit comments

Comments
 (0)