ai-skills-api/SETUP.md

# Setup Guide: AI Skills API

This guide covers exactly how to deploy the AI Skills API on your home server (`helm`) and set up new agent projects.

## Prerequisites

- Docker & Docker Compose installed on `helm`
- Access to `helm` from your development machine (SSH or local)
- Optional: Claude Desktop with MCP support

## Server Setup (One-Time)

Deploy the AI Skills API service on your home server.

### 1. Clone the Repository

```bash
# On helm (or accessible to docker)
cd /opt
git clone ssh://git@helm:222/helm/ai-skills-api.git
cd ai-skills-api
```

### 2. Build and Start Services

```bash
# Build and start all services (API + Ollama + MCP)
docker compose up -d --build

# Check it's running
docker compose ps
# Should show: api, ollama, mcp (all "Up")
```

### 3. Verify Deployment

```bash
# Health check (from helm)
curl http://localhost:8675/health

# Expected response: {"status":"healthy"}
```

### 4. Configure Optional Settings

Edit `config.yaml` (creates defaults if missing):

```yaml
port: 8675
rag:
  max_skills: 3
  max_conventions: 2
  max_snippets: 2
compression:
  enabled: true
  strategy: "extractive"  # or "ollama" for phi-3-mini
auth:
  enabled: false  # set to true to require API key
  api_key: "your-secret-key-here"
```

Restart after changes:

```bash
docker compose restart
```

### 5. (Optional) Enable API Authentication

If you want auth across your network:

1. Edit `config.yaml`:
   ```yaml
   auth:
     enabled: true
     api_key: "generate-a-strong-random-key"
   ```

2. Restart:
   ```bash
   docker compose restart
   ```

3. Test:
   ```bash
   curl http://helm:8675/health  # Should work (no auth)
   curl http://helm:8675/skills  # Should fail 401 if auth enabled
   curl -H "X-API-Key: your-secret-key-here" http://helm:8675/skills  # Should work
   ```

**Note**: API is accessible only on your home network (`helm:8675`). No public exposure by default.

### Access from Other Machines

Your agents running on other machines can access the API at `http://helm:8675`.

```bash
# From any machine on your network
curl http://helm:8675/health
```

If DNS isn't set up, use `helm` directly (should resolve via local network or hosts file).

## MCP Server for Claude Desktop / OpenCode

The stack includes an MCP server that exposes your skills to Claude Desktop or OpenCode via the Model Context Protocol.

### What's Running

- **MCP Server**: SSE mode on `http://helm:3000`
- Automatically proxies requests to the Skills API (`http://api:8080` internally)
- Same Docker network, no extra configuration needed

### Configure Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "skills": {
      "url": "http://helm:3000"
    }
  }
}
```

Restart Claude. You should see `skills` server connected with tools like `search_skills`, `get_context`, etc.

### Configure OpenCode

See [OPENCODE-MCP.md](OPENCODE-MCP.md) for detailed instructions. In short:

```bash
# Run the setup script from the agentic-templates repo:
cd ~/projects/agentic-templates
./setup-opencode-mcp.sh

# Or manually create ~/.config/opencode/mcp.json:
{
  "mcpServers": {
    "skills": {
      "url": "http://helm:3000"
    }
  }
}
```

### Test MCP Connection

```bash
# Should hang (SSE stream) if connected
curl http://helm:3000/sse

# With API key if auth enabled:
curl -H "X-API-Key: your-key" http://helm:3000/sse
```

## Project Setup (Per Project/Session)

For each new project or AI agent, you'll create an integration that uses the API.

### Option A: Use the Template Repository (Recommended)

We maintain a template repo for quick starts.

#### 1. Clone the Template

```bash
cd ~/projects  # or wherever you keep projects
git clone git.bouncypixel.com:helm/agentic-templates.git my-agent
cd my-agent
```

Or clone directly via SSH:

```bash
git clone ssh://git@helm:222/helm/agentic-templates.git my-agent
```

#### 2. Configure Environment

Copy `.env.example` to `.env`:

```bash
cp .env.example .env
```

Edit `.env` if needed:

```env
API_URL=http://helm:8675
API_KEY=  # Only if auth enabled
PROJECT=/path/to/your/project  # Optional, for context scoping
```

#### 3. Run Your Agent

```bash
# Using Docker Compose (recommended)
docker compose up -d

# Or run directly
pip install -r requirements.txt
python agent.py
```

The agent will automatically:
- Fetch relevant skills/conventions via RAG
- Store decisions in memory
- Compress conversation when it grows large

### Option B: Manual Integration

If you want to integrate into an existing project:

1. Install the Python dependency:

```bash
pip install httpx
```

2. Copy the integration pattern from `template/agent.py` (the `get_context`, `compress_messages`, `store_memory` functions).

3. Add these calls to your agent's workflow:

   - Before each LLM call: `context = await get_context(query, project)`
   - Inject context into system prompt
   - After each response: `await store_memory(project, key, content)`
   - When conversation > 10 messages: `compressed = await compress_messages(conversation)`

See `USAGE.md` for detailed integration patterns.

## Seeding Skills and Conventions

The API comes with a seed script that adds useful skills.

### Run the Seed Script

```bash
cd /opt/ai-skills-api
python examples/seed-data.py
```

This adds:
- D&D campaign management skills
- Infrastructure/Docker skills
- Code review skills
- General best practices

### Add Custom Skills

#### Via API:

```bash
curl -X POST http://helm:8675/skills \
  -H "Content-Type: application/json" \
  -d '{
    "id": "my-skill",
    "name": "My Custom Skill",
    "category": "custom",
    "content": "Specific instructions for your agent...",
    "tags": ["keyword1", "keyword2"]
  }'
```

#### Via MCP (Claude Desktop):

Use the `skills/create_skill` tool directly in Claude.

#### Via Python:

```python
import httpx

resp = httpx.post(
    "http://helm:8675/skills",
    json={
        "id": "unique-skill-id",
        "name": "Skill Name",
        "category": "category",
        "content": "Full skill instructions...",
        "tags": ["tag1", "tag2"]
    }
)
```

### Add Project Conventions

Conventions are project-specific (tied to a project path or identifier):

```bash
curl -X POST http://helm:8675/conventions \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Project Conventions",
    "project": "/home/user/myproject",
    "content": "Project-specific coding standards, workflows, etc."
  }'
```

## Testing Your Setup

### 1. Test RAG Context

```bash
curl "http://helm:8675/context/rag?query=docker compose&project=test"
```

Should return JSON with `skills`, `conventions`, `snippets` arrays.

### 2. Test Compression

```bash
curl -X POST http://helm:8675/compress \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "Hello!"},
      {"role": "assistant", "content": "Hi there! How can I help?"},
      {"role": "user", "content": "Tell me about Docker."},
      {"role": "assistant", "content": "Docker is a containerization platform..."}
    ]
  }'
```

Should return compressed messages and `tokens_saved`.

### 3. Test Memory

```bash
curl -X POST http://helm:8675/memory \
  -H "Content-Type: application/json" \
  -d '{
    "project": "test",
    "key": "decision-123",
    "content": "We decided to use FastAPI for this project"
  }'

curl "http://helm:8675/memory?project=test"
```

### 4. Test from Agent Template

```bash
cd ~/projects/my-agent
docker compose up -d
docker compose logs -f agent  # Watch the agent start and interact
```

## Troubleshooting

### Service Won't Start

```bash
# Check logs
docker compose logs ai-skills-api

# Common issues:
# - Port 8675 already in use: change port in docker-compose.yml
# - Permissions: ensure /opt/ai-skills-api is readable
```

### Ollama Not Pulling Model

The entrypoint script auto-pulls `phi3:mini` if compression strategy is `ollama`. To force:

```bash
docker compose exec ai-skills-api ollama pull phi3:mini
```

### Can't Connect from Other Machines

- Ensure `helm` is reachable on the network (ping `helm`)
- Check Docker network: `docker network ls` (should have `ai-skills-api_default`)
- API is bound to `0.0.0.0:8675` inside container - accessible from host and other containers

### Auth Errors

- If you get 401, either disable auth in `config.yaml` or set `API_KEY` in your agent's `.env`
- Verify: `curl -H "X-API-Key: your-key" http://helm:8675/skills`

### High RAG Latency (>10ms)

- First request after startup will be slower (warming cache)
- Subsequent queries should be <5ms
- If still slow, check embedding model load: `docker compose logs ai-skills-api`

## Next Steps

- Read `USAGE.md` for detailed integration patterns and best practices
- Use the template repo for all new agent projects
- Add project-specific skills and conventions as you work
- Monitor logs for token savings