Roo Standalone - AI Agent Service

A standalone FastAPI microservice for the Roo AI agent with PostgreSQL + pgvector for vector embeddings and a skills-based architecture.

Quick Start

# Install dependencies
pip install -r requirements.txt

# Run development server
uvicorn roo.main:app --reload

# Run with Docker
docker-compose up -d

Project Structure

roo-standalone/
├── roo/                    # Main application
│   ├── main.py             # FastAPI entrypoint
│   ├── config.py           # Settings
│   ├── agent.py            # Core agent
│   ├── llm.py              # LLM client
│   ├── database.py         # PostgreSQL + pgvector
│   ├── embeddings.py       # Vector embeddings
│   ├── slack_client.py     # Slack SDK
│   ├── skills/             # Skill system
│   └── clients/            # External API clients
├── skills/                 # Skill definitions (*.md)
├── tests/                  # Test suite
└── docker-compose.yml

Skills System

Skills are defined as markdown files in skills/. Each skill specifies:

• Trigger keywords
• Parameters to extract
• Actions to perform (LLM, database, API calls)

See skills/connect_users.md for an example.

Environment Variables

Copy roo-standalone/.env.example to roo-standalone/.env and configure:

• DATABASE_URL - PostgreSQL connection
• SLACK_BOT_TOKEN - Slack bot token
• OPENAI_API_KEY - For LLM and embeddings
• MLAI_BACKEND_URL - Backend API URL for points, admin lookup, and Luma attendee reports
• ROO_API_KEY/MLAI_API_KEY/INTERNAL_API_KEY - Backend auth key for Roo-to-mlai-backend calls

For Slack file parsing, the Roo Slack app must include the files:read bot scope. Contextual Linear commands additionally require channels:history/channels:read for public channels, groups:history/groups:read for private channels, and users:read plus users:read.email for reliable Slack-to-Linear identity matching. Reinstall the app after adding scopes. If Slack rotates the bot token during reinstall, update SLACK_BOT_TOKEN in production and restart Roo.

For daily jobs, the recommended production setup is:

• mlai-backend owns the 7am Melbourne scheduler and Slack posting
• Roo keeps JOBS_SCHEDULER_ENABLED=false
• Roo only needs JOBS_API_URL and JOBS_TRIGGER_TOKEN if you want it to trigger backend jobs manually in the future