Skip to content

README.md

Latest commit

 

History

History
179 lines (137 loc) · 5.7 KB

README.md

File metadata and controls

179 lines (137 loc) · 5.7 KB

OpsForge AI

An AI-powered operations assistant for small and mid-sized teams. Run your operations — time tracking, task management, scheduling, leave, and reporting — by talking to specialized AI agents, alongside a modern dashboard UI.

Built to run on a 100% free stack: no paid services required.

✨ Features

  • Conversational AI agents (Clock, Task, Report) — streamed token-by-token.
  • Kanban task board with drag-and-drop and live multi-user updates.
  • Attendance — live clock-in/out with a running timer and history.
  • Shift scheduling — weekly grid with overlap/conflict detection.
  • Leave management — request / approve / reject with balances.
  • Reports — AI-generated reports + an emailed AI Weekly Briefing.
  • RAG knowledge base — agents answer from your company docs (pgvector).
  • Notifications — in-app notification center, delivered in real time.
  • Real-time everything — WebSocket push so dashboards stay live.
  • Audit trail & manager overrides — every AI action is logged.
  • Role-based access (admin / manager / employee), JWT auth with refresh-token rotation + reuse detection, rate limiting, and security headers.
  • Installable PWA with light/dark "Harbor" theme.

🛠️ Tech stack (all free)

Layer Technology
Backend FastAPI, LangChain, SQLAlchemy, Alembic
LLM Groq (Llama 3.1) — free tier
Embeddings fastembed (local ONNX, bge-small-en-v1.5) — no API key
Vector store pgvector (in PostgreSQL) — no external service
Database PostgreSQL (prod) / SQLite (quick local dev)
Frontend React, Tailwind CSS, shadcn-style UI, Recharts, @dnd-kit
Realtime WebSockets
Email (optional) Resend free tier, SMTP, or SendGrid
Notifications (optional) Slack incoming webhook
Infra Docker / Docker Compose, Nginx

📋 Prerequisites

  • Python 3.11, Node 18+
  • A free Groq API key → https://console.groq.com
  • For RAG: PostgreSQL with the pgvector extension (or a free hosted Postgres such as Neon/Supabase). Optional — the app runs on SQLite without it.
  • Optional: Resend/SMTP (email), Slack webhook.

🚀 Quick start

1. Configure environment

cp .env.example .env

Set at minimum:

GROQ_API_KEY=your_key_here
SECRET_KEY=<python -c "import secrets; print(secrets.token_urlsafe(48))">

Option A — Local, SQLite (fastest, no DB install)

Best for trying the app. Everything works except vector RAG.

In .env:

DATABASE_URL=sqlite:///./ai_operations.db

# Backend
python -m venv venv311
source venv311/bin/activate        # Windows: .\venv311\Scripts\Activate.ps1
pip install -r requirements.txt
uvicorn backend.api.main:app --reload --port 8000

# Frontend (second terminal)
cd frontend
npm install
npm start

Option B — Docker (full stack incl. pgvector RAG)

docker compose up --build -d

Option C — Local with full RAG, no Docker

Point DATABASE_URL at any PostgreSQL that has pgvector — including a free hosted one (Neon, Supabase), which support CREATE EXTENSION vector:

DATABASE_URL=postgresql://user:pass@host:5432/dbname

Then run the backend/frontend as in Option A. The pgvector extension and the embedding model are set up automatically on first start.

🔑 Environment variables

Variable Required Notes
GROQ_API_KEY ✅ LLM provider (free)
SECRET_KEY ✅ (prod) JWT signing; a dev key is generated if unset
DATABASE_URL ✅ sqlite:///./ai_operations.db or postgresql://…
CORS_ORIGINS – Comma-separated; default http://localhost:3000
EMBEDDING_MODEL / EMBEDDING_DIM – Defaults to bge-small-en-v1.5 / 384
RESEND_API_KEY / FROM_EMAIL – Enables email + weekly briefing
SMTP_* / SENDGRID_API_KEY – Alternative email providers
SLACK_WEBHOOK_URL – Outbound Slack notifications
SENTRY_DSN – Error tracking

All optional integrations no-op gracefully when unset.

🗄️ Database migrations (Alembic)

The schema also auto-creates on startup (dev convenience). For migration-driven workflows:

alembic upgrade head                          # apply migrations
alembic revision --autogenerate -m "message"  # after changing models

See alembic/README.md.

📁 Project structure

backend/
  agents/        # AI agents (clock, task, report) + manager
  api/           # FastAPI app, routers, websocket, limiter, notifications
  database/      # SQLAlchemy models + connection + seed
  rag/           # pgvector store + retriever + document loader
  tools/         # LangChain tools used by agents
  utils/         # llm factory, security, email, slack, logging
frontend/
  src/components/ # UI primitives (shadcn-style), layout, nav
  src/pages/      # Landing, Dashboard, Tasks, Attendance, Schedule, Leave,
                  # Reports, Employees, AgentChat, AgentHistory, Login, Register
  src/contexts/   # Auth + Theme
  src/services/   # API client + SSE streaming
alembic/          # migrations
docker-compose.yml, Dockerfile.*, nginx.conf

🔒 Security notes

  • JWT access + refresh tokens with rotation and reuse detection.
  • Public registration creates employee accounts only (no role self-assignment).
  • Rate limiting on auth + agent endpoints, CORS locked to configured origins, security headers, and structured logging.

📝 License

Internal project. See repository for details.