grimlock/QUICKSTART.md

Grimlock Quick Start Guide

Get Grimlock running in 5 minutes.

Prerequisites

• Python 3.11+
• Anthropic API key (get one here)
• OR Docker + Docker Compose

Option 1: Quick CLI Test (Fastest)

# Clone the repo (if not already)
git clone https://gittea.979labs.com/amitis55/grimlock.git
cd grimlock

# Set up environment
cp backend/.env.example backend/.env
# Edit backend/.env and add your ANTHROPIC_API_KEY

# Install dependencies
pip install -r backend/requirements.txt

# Run CLI
python cli.py

You should see:

============================================================
GRIMLOCK CLI
============================================================

Initializing...
Context loaded: {'projects': 1, 'patterns': 0, 'anti_patterns': 0, 'cost_models': 0, 'repos': 0}
AI client ready

Grimlock is online. Type 'exit' to quit.

You: 

Option 2: Run Backend Server

# From grimlock directory
cd backend

# Set up environment
cp .env.example .env
# Edit .env and add your ANTHROPIC_API_KEY

# Install dependencies
pip install -r requirements.txt

# Run server
python main.py

Server will start at http://localhost:8000

Test it:

curl http://localhost:8000/api/health

Option 3: Docker Compose (Production-like)

# From grimlock directory
cp backend/.env.example backend/.env
# Edit backend/.env and add your ANTHROPIC_API_KEY

# Start services
docker-compose up -d

# Check logs
docker-compose logs -f grimlock-backend

# Test
curl http://localhost:8000/api/health

Testing the Chat API

Using curl:

curl -X POST http://localhost:8000/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "What is Grimlock?"}
    ]
  }'

Using Python:

import requests

response = requests.post(
    "http://localhost:8000/api/chat",
    json={
        "messages": [
            {"role": "user", "content": "What projects does Vector Zulu have?"}
        ],
        "role": "engineer"
    }
)

print(response.json()["response"])

Adding Vector Zulu Context

Add your project summaries, patterns, and other context:

# Create context files
mkdir -p backend/context/projects
mkdir -p backend/context/patterns
mkdir -p backend/context/anti_patterns
mkdir -p backend/context/cost_models

# Add UTILEN project
cp path/to/UTILEN-summary.md backend/context/projects/utilen.md

# Add Vector Zulu platform
cp path/to/VectorZulu-summary.md backend/context/projects/vector-zulu.md

# Add patterns
echo "# Multi-Tenant SaaS Pattern

Based on UTILEN architecture:
- FastAPI + PostgreSQL + Redis + Celery
- Tenant isolation at DB and storage level
- Background processing for heavy operations
- JWT auth (avoid Keycloak)
" > backend/context/patterns/multi-tenant-saas.md

Restart the server and Grimlock will have Vector Zulu context!

Example Interactions

Ask about projects:

You: What projects has Vector Zulu built?
Grimlock: Vector Zulu has built several major projects including UTILEN (an AI-powered document management system), the Vector Zulu distributed cyber range platform, and a Layer 1 blockchain with stablecoin...

Get architecture advice:

You: I need to build a document processing system
Grimlock: Based on Vector Zulu patterns, this maps to the UTILEN architecture: FastAPI + PostgreSQL + Redis + Celery + MinIO + Claude Vision API...

Role-specific responses:

# As engineer
response = requests.post("http://localhost:8000/api/chat", json={
    "messages": [{"role": "user", "content": "How should I implement multi-tenancy?"}],
    "role": "engineer"
})

# As BD person
response = requests.post("http://localhost:8000/api/chat", json={
    "messages": [{"role": "user", "content": "What's our pricing for UTILEN?"}],
    "role": "bd"
})

Next Steps

1. Add more context - The more context you add, the smarter Grimlock becomes
2. Build the web interface - See frontend/ directory
3. Deploy to your infrastructure - Use Docker Compose on your servers
4. Integrate with your systems - Build connectors for git, databases, etc.

Troubleshooting

"ANTHROPIC_API_KEY not set"

• Make sure you copied .env.example to .env and added your API key

"Context manager not initialized"

• The backend/context directory needs to exist
• Run mkdir -p backend/context/{projects,patterns,anti_patterns,cost_models}

"Module not found"

• Make sure you installed requirements: pip install -r backend/requirements.txt

Docker issues

• Make sure Docker daemon is running
• Check logs: docker-compose logs -f

Support

Questions? Open an issue on the repo or contact the Vector Zulu team.

---

Built with ❤️ by Vector Zulu