grimlock/QUICKSTART.md

# Grimlock Quick Start Guide

Get Grimlock running in 5 minutes.

## Prerequisites

- Python 3.11+
- Anthropic API key ([get one here](https://console.anthropic.com/))
- OR Docker + Docker Compose

## Option 1: Quick CLI Test (Fastest)

```bash
# 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

```bash
# 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:
```bash
curl http://localhost:8000/api/health
```

## Option 3: Docker Compose (Production-like)

```bash
# 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:
```bash
curl -X POST http://localhost:8000/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "What is Grimlock?"}
    ]
  }'
```

Using Python:
```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:

```bash
# 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:**
```python
# 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**