Steev_code/QUICK_REFERENCE.md

# AI Agent Platform - Quick Reference Card

## 🚀 Quick Start

```bash
# Start everything
docker compose up -d

# Check status
docker compose ps

# View logs
docker compose logs -f api
```

## 🔗 Access Points

| Service | URL | Purpose |
|---------|-----|---------|
| **API** | http://localhost:6001/swagger | Interactive API docs |
| **Health** | http://localhost:6001/health | System health check |
| **Metrics** | http://localhost:6001/metrics | Prometheus metrics |
| **Langfuse** | http://localhost:3000 | Observability UI |
| **Ollama** | http://localhost:11434/api/tags | Model info |

## 💡 Common Commands

### Test AI Agent
```bash
# Simple test
echo '{"prompt":"Hello"}' | \
  curl -s -X POST http://localhost:6001/api/command/executeAgent \
  -H "Content-Type: application/json" -d @- | jq .

# Math calculation
echo '{"prompt":"What is 10 plus 5?"}' | \
  curl -s -X POST http://localhost:6001/api/command/executeAgent \
  -H "Content-Type: application/json" -d @- | jq .
```

### Check System Health
```bash
# API health
curl http://localhost:6001/health | jq .

# Ollama status
curl http://localhost:11434/api/tags | jq '.models[].name'

# Database connection
docker exec postgres pg_isready -U postgres
```

### View Logs
```bash
# API logs
docker logs svrnty-api --tail 50 -f

# Ollama logs
docker logs ollama --tail 50 -f

# Langfuse logs
docker logs langfuse --tail 50 -f

# All services
docker compose logs -f
```

### Database Access
```bash
# Connect to PostgreSQL
docker exec -it postgres psql -U postgres -d svrnty

# List tables
\dt agent.*

# Query conversations
SELECT * FROM agent.conversations LIMIT 5;

# Query revenue
SELECT * FROM agent.revenue ORDER BY year, month;
```

## 🛠️ Troubleshooting

### Container Won't Start
```bash
# Clean restart
docker compose down -v
docker compose up -d

# Rebuild API
docker compose build --no-cache api
docker compose up -d
```

### Model Not Loading
```bash
# Pull model manually
docker exec ollama ollama pull qwen2.5-coder:7b

# Check model status
docker exec ollama ollama list
```

### Database Issues
```bash
# Recreate database
docker compose down -v
docker compose up -d

# Run migrations manually
docker exec svrnty-api dotnet ef database update
```

## 📊 Monitoring

### Prometheus Metrics
```bash
# Get all metrics
curl http://localhost:6001/metrics

# Filter specific metrics
curl http://localhost:6001/metrics | grep http_server_request
```

### Health Checks
```bash
# Basic health
curl http://localhost:6001/health

# Ready check (includes DB)
curl http://localhost:6001/health/ready
```

## 🔧 Configuration

### Environment Variables
Key variables in `docker-compose.yml`:
- `ASPNETCORE_URLS` - HTTP endpoint (currently: http://+:6001)
- `OLLAMA_MODEL` - AI model name
- `CONNECTION_STRING_SVRNTY` - Database connection
- `LANGFUSE_PUBLIC_KEY` / `LANGFUSE_SECRET_KEY` - Tracing keys

### Files to Edit
- **API Configuration:** `Svrnty.Sample/appsettings.Production.json`
- **Container Config:** `docker-compose.yml`
- **Environment:** `.env` file

## 📝 Current Status

### ✅ Working
- HTTP API endpoints
- AI agent with qwen2.5-coder:7b
- PostgreSQL database
- Langfuse v2 observability
- Prometheus metrics
- Rate limiting (100 req/min)
- Health checks
- Swagger documentation

### ⏸️ Temporarily Disabled
- gRPC endpoints (ARM64 Mac compatibility issue)
- Port 6000 (gRPC was on this port)

### ⚠️ Known Cosmetic Issues
- Ollama shows "unhealthy" (but works fine)
- Langfuse shows "unhealthy" (but works fine)
- Database migration warning (safe to ignore)

## 🔄 Re-enabling gRPC

When ready to re-enable gRPC:

1. Uncomment in `Svrnty.Sample/Svrnty.Sample.csproj`:
   - `<Protobuf Include>` section
   - gRPC package references
   - gRPC project references

2. Uncomment in `Svrnty.Sample/Program.cs`:
   - `using Svrnty.CQRS.Grpc;`
   - Kestrel configuration
   - `cqrs.AddGrpc()` section

3. Update `docker-compose.yml`:
   - Uncomment port 6000 mapping
   - Add gRPC endpoint to ASPNETCORE_URLS

4. Rebuild:
   ```bash
   docker compose build --no-cache api
   docker compose up -d
   ```

## 📚 Documentation

- **Full Deployment Guide:** `DEPLOYMENT_SUCCESS.md`
- **Testing Guide:** `TESTING_GUIDE.md`
- **Project Documentation:** `README.md`
- **Architecture:** `CLAUDE.md`

## 🎯 Performance

- **Cold start:** ~5 seconds
- **Health check:** <100ms
- **Simple queries:** 1-2s
- **LLM responses:** 5-30s (depends on complexity)

## 🔒 Security

- Rate limiting: 100 requests/minute per client
- Database credentials: In `.env` file
- HTTPS: Disabled in current HTTP-only mode
- Langfuse auth: Basic authentication

## 📞 Quick Help

**Issue:** Container keeps restarting
**Fix:** Check logs with `docker logs <container-name>`

**Issue:** Can't connect to API
**Fix:** Verify health: `curl http://localhost:6001/health`

**Issue:** Model not responding
**Fix:** Check Ollama: `docker exec ollama ollama list`

**Issue:** Database error
**Fix:** Reset database: `docker compose down -v && docker compose up -d`

---

**Last Updated:** 2025-11-08
**Mode:** HTTP-Only (Production Ready)
**Status:** ✅ Fully Operational