Getting Started

The fastest way to run Aktilot is with Docker Compose. You need an OpenAI API key and Docker installed.

Terminal

git clone https://github.com/vikas0686/Aktilot.git
cd Aktilot
 
cp .env.example .env
# Open .env and set: OPENAI_API_KEY=sk-...
 
docker compose up --build

That's it. Create a project, upload a PDF, create an agent, and start asking questions. The Temporal UI at :8233 lets you monitor document processing jobs, inspect individual pipeline steps, and retry failed uploads without re-uploading the file.

Services

Service	URL	Purpose
App	http://localhost:3000	Main UI
Backend API	http://localhost:8000	REST API + OpenAPI docs at /docs
Temporal UI	http://localhost:8233	Workflow execution history and retries
Grafana	http://localhost:3002	Observability dashboards (admin / admin)
Prometheus	http://localhost:9090	Metrics query engine

Local Development

Prerequisites: Python 3.12+, Node 20+, Docker (for Postgres + Temporal)

Backend

Terminal

cd backend
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
 
cp .env.example .env   # set OPENAI_API_KEY and DATABASE_URL
 
# Start Postgres and Temporal via Docker
docker compose up postgres temporal -d
 
alembic upgrade head
 
# Terminal 1 — API server
uvicorn main:app --reload --port 8000
 
# Terminal 2 — Temporal worker (processes document uploads)
python -m temporal.worker

Frontend

Terminal

cd frontend
npm install
npm run dev   # http://localhost:5173

Tests

Terminal

# Backend
cd backend && source .venv/bin/activate
pytest --tb=short -q
 
# Frontend
cd frontend && npm test

Environment Variables

Copy .env.example to .env in the project root (for Docker) or backend/.env (for local dev).

Variable	Required	Description
OPENAI_API_KEY	Yes	Your OpenAI API key
DATABASE_URL	Yes	PostgreSQL connection string (asyncpg)
TEMPORAL_ADDRESS	No	Temporal server address (default: localhost:7233)
CHAT_MODEL	No	Chat model to use (default: gpt-4o-mini)
EMBEDDING_MODEL	No	Embedding model (default: text-embedding-3-small)
UPLOAD_DIR	No	Where uploaded files are stored (default: uploads)
CHROMA_DIR	No	Where vector data is persisted (default: chroma_data)