curl -fsSL https://raw.githubusercontent.com/Kocoro-lab/Shannon/v0.1.0/scripts/install.sh | bash

# Submit a task
curl -X POST http://localhost:8080/api/v1/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What is the capital of France?",
    "session_id": "demo-session"
  }'

# Response: {"task_id":"task-dev-123","status":"running"}

# Stream events in real-time
curl -N "http://localhost:8080/api/v1/stream/sse?workflow_id=task-dev-123"

# Get final result
curl "http://localhost:8080/api/v1/tasks/task-dev-123"

pip install shannon-sdk

shannon submit "What is the capital of France?"

cd desktop
npm install
npm run tauri:build  # Builds for your platform

# In a new terminal (backend should already be running)
cd desktop
npm install
npm run dev

# Open http://localhost:3000 in your browser

# Web Search (choose one provider)
WEB_SEARCH_PROVIDER=serpapi             # serpapi | google | bing | exa
SERPAPI_API_KEY=your-serpapi-key        # serpapi.com
# OR
GOOGLE_SEARCH_API_KEY=your-google-key   # Google Custom Search
GOOGLE_SEARCH_ENGINE_ID=your-engine-id

# Web Fetch/Crawl (for deep research)
WEB_FETCH_PROVIDER=firecrawl            # firecrawl | exa | python
FIRECRAWL_API_KEY=your-firecrawl-key    # firecrawl.dev (recommended for production)

# Drop-in replacement for OpenAI API
export OPENAI_API_BASE=http://localhost:8080/v1
# Your existing OpenAI code works unchanged

# Monitor agent execution in real-time (SSE)
curl -N "http://localhost:8080/api/v1/stream/sse?workflow_id=task-dev-123"

# Events include:
# - WORKFLOW_STARTED, WORKFLOW_COMPLETED
# - AGENT_STARTED, AGENT_COMPLETED
# - TOOL_INVOKED, TOOL_OBSERVATION
# - LLM_PARTIAL, LLM_OUTPUT

# Multi-agent research with automatic synthesis
curl -X POST http://localhost:8080/api/v1/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Compare renewable energy adoption in EU vs US",
    "context": {
      "force_research": true,
      "research_strategy": "deep"
    }
  }'
# Orchestrates multiple research agents and synthesizes findings with citations

# Multi-turn conversations with context memory
curl -X POST http://localhost:8080/api/v1/tasks \
  -H "Content-Type: application/json" \
  -d '{"query": "What is GDP?", "session_id": "econ-101"}'

# Follow-up remembers previous context (within history window)
curl -X POST http://localhost:8080/api/v1/tasks \
  -H "Content-Type: application/json" \
  -d '{"query": "How does it relate to inflation?", "session_id": "econ-101"}'
# Agent recalls recent conversation history from the same session

# Run tasks on a schedule (cron syntax)
curl -X POST http://localhost:8080/api/v1/schedules \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Daily Market Analysis",
    "cron_expression": "0 9 * * *",
    "task_query": "Analyze market trends",
    "max_budget_per_run_usd": 0.50
  }'

# Production agent failed? Replay it locally step-by-step
./scripts/replay_workflow.sh task-prod-failure-123

# Output shows every decision, tool call, and state change

curl -X POST http://localhost:8080/api/v1/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Generate a market analysis report",
    "config": {
      "budget": {
        "max_tokens": 5000,
        "fallback_model": "gpt-5-mini-2025-08-07"
      }
    }
  }'
# Automatically switches to cheaper model when 80% budget consumed

# Python runs in isolated WASI sandbox — no network, read-only FS
./scripts/submit_task.sh "Execute Python: import os; os.system('rm -rf /')"
# Result: OSError - system calls blocked by WASI sandbox

# Check all services
docker compose -f deploy/compose/docker-compose.release.yml ps

# Gateway health
curl http://localhost:8080/health

# Admin health
curl http://localhost:8081/health

# All services
docker compose -f deploy/compose/docker-compose.release.yml logs -f

# Specific service
docker compose -f deploy/compose/docker-compose.release.yml logs -f orchestrator
docker compose -f deploy/compose/docker-compose.release.yml logs -f gateway
docker compose -f deploy/compose/docker-compose.release.yml logs -f llm-service

# Clone the repository
git clone https://github.com/Kocoro-lab/Shannon.git
cd Shannon

# Setup development environment
make setup                              # Creates .env, generates proto files
echo "OPENAI_API_KEY=sk-..." >> .env    # Add your API key
./scripts/setup_python_wasi.sh          # Download Python WASI interpreter (~20MB)

# Start all services (builds locally)
make dev

# Run tests
make smoke  # E2E smoke tests
make ci     # Full CI suite

cd Shannon
cp .env.example .env
nano .env  # Add your API keys
docker compose -f deploy/compose/docker-compose.release.yml up -d

make lint   # Run linters (Go, Rust, Python)
make fmt    # Format code
make proto  # Regenerate proto files
make logs   # View service logs
make ps     # Service status
make down   # Stop all services