🚀 Getting Started

Get IntentScope running locally in under 10 minutes.

Prerequisites

Docker Desktop & Docker Compose
Node.js ≥ 20
Python ≥ 3.11
Go ≥ 1.22
A Clerk account (free tier)
A Groq API key (free) — or Mistral AI / Ollama

Clone & Configure

git clone https://github.com/hg-ppp-2807-dev/intent-scope.git
cd intent-scope
 
cp .env.example .env

Now open .env and fill in your keys:

# Database
DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5434/intentscope

# Clerk Auth
CLERK_SECRET_KEY=sk_test_...
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...

# LLM — pick at least one
GROQ_API_KEY=gsk_...          # Recommended: free & fast
MISTRAL_API_KEY=               # Alternative

# Frontend
NEXT_PUBLIC_API_URL=http://localhost:8000

Start Infrastructure

docker compose up -d

This starts PostgreSQL (port 5434) and Ollama (port 11434).

# Optional — pull a local LLM model (~2GB)
docker exec intentscope-ollama ollama pull llama3.2

Run Database Migrations

cd backend-python
pip install -r requirements.txt
alembic upgrade head

Start the API Gateway

uvicorn app.main:app --reload --port 8000

Verify it’s running:

curl http://localhost:8000/health
# {"status":"healthy","db":"connected"}

Interactive API docs: http://localhost:8000/docs

Start the Go Token Validator

cd backend-go
go run main.go

The validator runs on port 8081 and provides a fast-path /validate endpoint.

Start the Frontend

Create frontend/.env.local:

NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
CLERK_SECRET_KEY=sk_test_...
NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in
NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up
NEXT_PUBLIC_API_URL=http://localhost:8000

cd frontend
npm install
npm run dev

Open http://localhost:3000 → Sign in → Dashboard ✅

Your First API Call

Once running, create a virtual API key in the dashboard and make a request:

curl -X POST http://localhost:8000/v1/chat/completions \
  -H "Authorization: Bearer sk-intentscope-your-virtual-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "default",
    "messages": [{"role": "user", "content": "Explain async/await in Python"}]
  }'

IntentScope will:

Validate your virtual key
Analyze the prompt intent (code_gen, high complexity)
Route to the heavy model tier automatically
Return the response with full usage tracking

Set "model": "default" to let IntentScope choose the best model automatically based on intent analysis.

Introduction Architecture