Skip to content

Latest commit

 

History

History
314 lines (235 loc) · 7.33 KB

local-development.md

File metadata and controls

314 lines (235 loc) · 7.33 KB

Local Development Guide

Run Wingman bot locally with live streaming support.

Prerequisites

  • Python 3.11+ (for local bot development)
  • Docker & Docker Compose (for services)
  • Slack workspace with admin access
  • OpenRouter or OpenAI API key

1. Get Slack App Credentials

Option A: Use Existing App

If you already have a Slack app:

  1. Go to api.slack.com/apps → select your app
  2. Get Bot Token: OAuth & Permissions → Bot User OAuth Token (xoxb-...)
  3. Get App Token: Basic Information → App-Level Tokens → Generate (xapp-...)
  4. Get Signing Secret: Basic Information → Signing Secret

Option B: Create New App

# 1. Go to https://api.slack.com/apps and create a new app
# 2. Name it "Wingman-dev" for local testing

Required Scopes (OAuth & Permissions):

app_mentions:read
channels:history
channels:read
chat:write
im:history
im:read
im:write
users:read

Enable Socket Mode (Basic Information):

  • Toggle Socket Mode ON
  • Generate App-Level Token with connections:write scope

Enable Events (Event Subscriptions):

  • Toggle ON
  • Subscribe to: app_mention, message.im

2. Environment Setup

cd wingman
cp .env.example .env

Edit .env:

# Required Slack Tokens
SLACK_BOT_TOKEN=xoxb-your-bot-token
SLACK_APP_TOKEN=xapp-your-app-token
SLACK_SIGNING_SECRET=your-signing-secret

# AI Provider (choose one)
OPENROUTER_API_KEY=sk-or-your-key
# OR
OPENAI_API_KEY=sk-your-key

# Model
LLM_MODEL=openai/gpt-4-turbo-preview
LLM_TEMPERATURE=0.7
LLM_MAX_TOKENS=2000

3. Start Supporting Services

docker compose up -d postgres chroma

Verify:

docker compose ps

4. Run Bot Locally

Using mise (recommended)

mise run dev-bot

Or directly

cd backend
uv sync
python run_bot.py

Verify Bot is Running

# Check logs
docker compose logs -f bot

# Or if running directly, you should see:
# INFO:slack_bolt.adapter.socket_mode.base_socket_mode:Starting Socket Mode handler...

5. Test in Slack

DM the Bot

  • Open Slack DM to @Wingman
  • Send: Hello!
  • You should see streaming thinking steps appear

Mention in Channel

  • Invite bot: /invite @Wingman
  • Post: @Wingman what's the status?
  • Watch the streaming response

Use Slash Command

  • Type: /wingman hello

6. Streaming Behavior

When streaming is working, you should see:

🧠 Processing your request...
  ✅ Analyzing question...
  🔍 Searching knowledge base...
  ✅ Searching knowledge base...
  ✍️ Generating response...
  ✅ Generating response...

[Full answer appears here]

The thinking steps show the bot's reasoning process in real-time.

Troubleshooting

Bot Not Responding

# Check bot logs
docker compose logs -f bot

# Common fixes:
# 1. Verify SLACK_BOT_TOKEN starts with xoxb-
# 2. Verify SLACK_APP_TOKEN starts with xapp-
# 3. Verify Socket Mode is enabled in Slack app settings
# 4. Verify Event Subscriptions are configured

Streaming Not Working

  1. Verify slack-sdk version is 3.40.0+:

    pip show slack-sdk | grep Version
  2. Check streaming is enabled in your Slack app:

    • App settings → Socket Mode → should be ON
    • App settings → Event Subscriptions → should be ON
  3. Test with a simple message first

Database Errors

# Reset database
docker compose down -v
docker compose up -d postgres chroma

Port Conflicts

If ports 5432 or 8001 are in use:

# Edit docker-compose.yaml to change ports

Mise Commands Reference

Wingman uses mise for task management. All tasks are defined in mise.toml.

Docker Services

mise run up              # Start all services
mise run down            # Stop all services
mise run restart         # Restart all services
mise run ps              # Show running services
mise run logs            # Tail all logs
mise run logs-bot        # Tail bot logs
mise run logs-backend    # Tail backend logs
mise run logs-frontend   # Tail frontend logs
mise run clean           # Remove containers and volumes

Local Development

mise run dev-backend     # Run backend API locally (port 8000)
mise run dev-bot         # Run bot locally (with streaming)
mise run dev-frontend    # Run frontend locally (port 3000)

Dependencies

mise run install         # Install all dependencies
mise run install-backend # Install backend deps (uv sync)
mise run install-frontend # Install frontend deps (bun install)

Database

mise run migrate              # Run pending migrations
mise run migrate-down         # Rollback last migration
mise run migrate-create       # Create new migration (set MIGRATION_MESSAGE=...)
mise run migrate-history      # Show migration history
mise run migrate-current      # Show current version
mise run shell-db             # Open PostgreSQL shell

Testing

mise run test             # Run all tests
mise run test-backend     # Run backend tests
mise run test-frontend    # Run frontend tests

Terraform (Slack App IaC)

mise run tf-init              # Initialize Terraform
mise run tf-plan              # Plan changes
mise run tf-apply             # Apply changes (creates Slack app)
mise run tf-destroy            # Destroy resources
mise run tf-output             # Show outputs
mise run tf-credentials       # Show Slack credentials (sensitive!)
mise run tf-sync-vars          # Sync .env → Terraform Cloud
mise run tf-load-vars         # Load Terraform Cloud → .env
mise run tf-oauth-url         # Show OAuth install URL

Full List

mise tasks

Development Workflow

Run All Services

# Terminal 1: Backend API
mise run dev-backend

# Terminal 2: Bot (with streaming)
mise run dev-bot

# Terminal 3: Frontend
mise run dev-frontend

Rebuild After Changes

# For Docker deployment
docker compose up -d --build bot

# For local
cd backend && uv sync

Search saved documents

GET /api/documents accepts an optional q parameter to search document titles and full content for a case-insensitive literal substring. Surrounding whitespace is ignored; an omitted or blank query returns the usual list. Characters such as % and _ are literal text, not search wildcards.

curl -sS --get http://localhost:8000/api/documents \
  --data-urlencode 'q=VPN' \
  --data-urlencode 'source=api' \
  --data-urlencode 'limit=10' \
  --data-urlencode 'offset=0'

Search and source filters combine before counting and pagination. The response keeps the existing items, total, limit and offset fields and newest-first ordering. A search with no matches returns an empty page with total set to zero. This searches saved PostgreSQL records and does not call Slack, embeddings or the model.

In the dashboard, open Documents, enter text in Search documents and submit Search. Results are paginated in groups of 20; Previous and Next keep the submitted search. Clear search returns to the first page of all saved documents. Typing does not send a request until the form is submitted. Selecting a result displays its full saved content.

Next Steps