### Install Dependencies and Start Development Server (Local Web UI)

Source: https://github.com/kocoro-lab/shannon/blob/main/desktop/README.md

Installs project dependencies and starts the Next.js development server for local web UI access. This option is for development and testing.

```bash
cd desktop

# Install dependencies
npm install

# Start development server
npm run dev

# Open http://localhost:3000
```

--------------------------------

### Start Services with Docker

Source: https://github.com/kocoro-lab/shannon/blob/main/CONTRIBUTING.md

Use 'make dev' to start all services with Docker for development. Use 'make smoke' to verify the setup.

```bash
# Option 1: Start all services with Docker (recommended)
make dev
make smoke  # Verify everything is working
```

--------------------------------

### Install jq for cURL Examples

Source: https://github.com/kocoro-lab/shannon/blob/main/examples/openai-sdk/README.md

Install jq, a lightweight and flexible command-line JSON processor, required for the cURL examples.

```bash
# jq for JSON parsing (required for this script)
brew install jq  # macOS
apt install jq   # Ubuntu/Debian
```

--------------------------------

### Development Setup and Run

Source: https://github.com/kocoro-lab/shannon/blob/main/python/llm-service/README.md

Steps to set up the development environment, including creating a virtual environment, installing dependencies, setting API keys, and running the service locally. The service will be accessible at http://localhost:8000.

```bash
# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Set environment variables
export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="..."

# Run locally
python main.py

# Service will be available at http://localhost:8000
```

--------------------------------

### One-liner User Installation

Source: https://github.com/kocoro-lab/shannon/blob/main/docs/release-process.md

This command installs Shannon by downloading the release configuration and starting all services. It fetches the specified version from GitHub.

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

--------------------------------

### Install Shannon with One Command

Source: https://github.com/kocoro-lab/shannon/blob/main/README.md

Use this command to download configuration, set up API keys, pull Docker images, and start Shannon services. Ensure Docker and Docker Compose are installed.

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

--------------------------------

### Install from Source

Source: https://github.com/kocoro-lab/shannon/blob/main/clients/python/PACKAGING.md

Installs the SDK in editable mode from a local source checkout. This is useful for development.

```bash
git clone https://github.com/Kocoro-lab/Shannon.git
cd Shannon/clients/python
pip install -e .
```

--------------------------------

### Install Dependencies and Run Tests (Go)

Source: https://github.com/kocoro-lab/shannon/blob/main/go/orchestrator/README.md

Installs project dependencies and runs all tests with race detection enabled. Ensure Go 1.21+ is installed.

```bash
go mod download

go test -race ./...
```

--------------------------------

### Start Docker Compose Stack

Source: https://github.com/kocoro-lab/shannon/blob/main/tests/README.md

Brings up the necessary services for testing using Docker Compose. Ensure Docker and Docker Compose are installed.

```bash
docker compose -f deploy/compose/docker-compose.yml up -d
```

--------------------------------

### Boot and Install App on Simulator

Source: https://github.com/kocoro-lab/shannon/blob/main/desktop/desktop-app-ios-build.md

Boots a specific simulator and installs the application bundle onto it. Replace the UDID with your target simulator's identifier.

```bash
# Boot simulator (replace UDID with your simulator)
xcrun simctl boot A278825B-AA30-45E0-B72A-DAF01C792F3A

# Install app to simulator
xcrun simctl install booted /path/to/shannon-desktop.app

# Launch app
xcrun simctl launch booted com.kocoro.shannon
```

--------------------------------

### Install App on Simulator via Drag-and-Drop

Source: https://github.com/kocoro-lab/shannon/blob/main/desktop/desktop-app-ios-build.md

Installs the application on a simulator by opening the Simulator app and dragging the `.app` bundle into it.

```bash
# Open Simulator.app
open -a Simulator

# Drag and drop the app bundle from Finder to install
```

--------------------------------

### Download and Install WebView2 Runtime

Source: https://github.com/kocoro-lab/shannon/blob/main/desktop/desktop-app-windows-build.md

Provide users with a direct link to download and install the WebView2 Runtime if it's not automatically handled by the installer.

```powershell
# Download and install WebView2 Runtime
# https://go.microsoft.com/fwlink/p/?LinkId=2124703
```

--------------------------------

### Install from PyPI

Source: https://github.com/kocoro-lab/shannon/blob/main/clients/python/PACKAGING.md

Installs the 'shannon-sdk' package from the Python Package Index (PyPI) after it has been published.

```bash
pip install shannon-sdk
```

--------------------------------

### User Installation Instructions for DMG

Source: https://github.com/kocoro-lab/shannon/blob/main/desktop/desktop-app-build-guide.md

Provides step-by-step instructions for end-users to download, verify, install, and launch the Shannon Desktop application from a DMG file.

```bash
1. **Download** `shannon-desktop_0.1.0_aarch64.dmg`
2. **Verify integrity** (optional but recommended):
   ```bash
   shasum -a 256 shannon-desktop_0.1.0_aarch64.dmg
   # Compare with published checksum
   ```
3. **Install**:
   - Double-click the DMG file
   - Drag "Shannon Desktop" to Applications folder
   - Eject the DMG
4. **Launch**:
   - Open from Applications folder
   - On first launch, right-click → Open (to bypass Gatekeeper)
   - Configure API endpoint in settings
```

--------------------------------

### Install Rust and Verify Node.js/Rust Installations

Source: https://github.com/kocoro-lab/shannon/blob/main/desktop/desktop-app-windows-build.md

Installs Rust via rustup and verifies the installations of Node.js, npm, Rust compiler, and Cargo. Also includes a link to download WebView2 if needed.

```powershell
# Install Rust (via rustup)
# Download and run: https://rustup.rs

# Verify installations
node --version
npm --version
rustc --version

```

```powershell
# Install WebView2 (if not present)
# Download: https://go.microsoft.com/fwlink/?LinkId=2124703
```

--------------------------------

### Copy Example .env File

Source: https://github.com/kocoro-lab/shannon/blob/main/docs/environment-configuration.md

Copy the example .env file to create your own configuration file. Edit this file with your actual API keys and sensitive information.

```bash
cp .env.example .env
# Edit .env with your actual API keys
```

--------------------------------

### Start Shannon Backend Services

Source: https://github.com/kocoro-lab/shannon/blob/main/desktop/README.md

Run the backend services before starting the desktop app. Verifies services are running.

```bash
# From repository root
make dev

# Verify services are running
curl http://localhost:8080/health
```

--------------------------------

### Install wabt on macOS

Source: https://github.com/kocoro-lab/shannon/blob/main/rust/agent-core/WASI_SETUP.md

Installs the WebAssembly Binary Toolkit (wabt) on macOS using Homebrew. Verify the installation by checking the version.

```bash
# Option 1: Install wabt (WebAssembly Binary Toolkit)
brew install wabt

# Verify installation
wat2wasm --version
```

--------------------------------

### Run an Example Script

Source: https://github.com/kocoro-lab/shannon/blob/main/clients/python/README.md

Command to navigate to the Python client directory and execute a specific example script, such as `simple_task.py`. This is useful for testing and understanding library functionality.

```bash
cd clients/python
python examples/simple_task.py
```

--------------------------------

### Install wabt on Linux from GitHub Releases

Source: https://github.com/kocoro-lab/shannon/blob/main/rust/agent-core/WASI_SETUP.md

Installs the WebAssembly Binary Toolkit (wabt) on Linux by downloading from GitHub releases and adding to the PATH.

```bash
# Alternative: Install from GitHub releases
wget https://github.com/WebAssembly/wabt/releases/download/1.0.34/wabt-1.0.34-linux.tar.gz
tar xzf wabt-1.0.34-linux.tar.gz
export PATH=$PATH:$(pwd)/wabt-1.0.34/bin
```

--------------------------------

### Start and Verify Shannon Services

Source: https://github.com/kocoro-lab/shannon/blob/main/tests/integration/README.md

Use these make commands to start all necessary Shannon services and then verify their health before running integration tests.

```bash
# Start all services
make dev
```

```bash
# Verify services are healthy  
make smoke
```

--------------------------------

### Upload to TestPyPI and Test Installation

Source: https://github.com/kocoro-lab/shannon/blob/main/clients/python/PACKAGING.md

Uploads the package to TestPyPI and then installs it in a clean virtual environment to verify the installation process and import functionality.

```bash
python3 -m twine upload -r testpypi dist/*

python3 -m venv test-env
source test-env/bin/activate
pip install -i https://test.pypi.org/simple/ shannon-sdk==0.7.0

python3 -c "from shannon import ShannonClient; print('✓ Import works')"
```

--------------------------------

### Install wabt on Linux (Arch Linux)

Source: https://github.com/kocoro-lab/shannon/blob/main/rust/agent-core/WASI_SETUP.md

Installs the WebAssembly Binary Toolkit (wabt) on Arch Linux using pacman.

```bash
# Arch Linux
sudo pacman -S wabt
```

--------------------------------

### Install from TestPyPI

Source: https://github.com/kocoro-lab/shannon/blob/main/clients/python/PACKAGING.md

Installs a specific version of the 'shannon-sdk' package from the TestPyPI repository.

```bash
pip install -i https://test.pypi.org/simple/ shannon-sdk==0.7.0
```

--------------------------------

### Install grpcurl

Source: https://github.com/kocoro-lab/shannon/blob/main/docs/ubuntu-quickstart.md

Installs grpcurl, a command-line tool for debugging gRPC services, essential for testing Shannon's gRPC interfaces.

```bash
wget https://github.com/fullstorydev/grpcurl/releases/download/v1.8.9/grpcurl_1.8.9_linux_x86_64.tar.gz
```

```bash
tar -xzf grpcurl_1.8.9_linux_x86_64.tar.gz
```

```bash
sudo mv grpcurl /usr/local/bin/
```

```bash
grpcurl --version
```

--------------------------------

### Install wabt on Linux (Ubuntu/Debian)

Source: https://github.com/kocoro-lab/shannon/blob/main/rust/agent-core/WASI_SETUP.md

Installs the WebAssembly Binary Toolkit (wabt) on Ubuntu or Debian-based Linux distributions using apt-get.

```bash
# Ubuntu/Debian
sudo apt-get update
sudo apt-get install wabt
```

--------------------------------

### Install Python OpenAI SDK

Source: https://github.com/kocoro-lab/shannon/blob/main/examples/openai-sdk/README.md

Install the official OpenAI Python SDK to use with Shannon.

```bash
pip install openai
```

--------------------------------

### Install WebAssembly Tools (wabt)

Source: https://github.com/kocoro-lab/shannon/blob/main/rust/agent-core/WASI_SETUP.md

Install the WebAssembly Binary Toolkit (WABT) for compiling WAT to WASM. Use package managers for macOS and Linux.

```bash
# macOS
brew install wabt

# Linux
sudo apt-get install wabt
```

--------------------------------

### Install LangChain OpenAI and LangChain

Source: https://github.com/kocoro-lab/shannon/blob/main/examples/openai-sdk/README.md

Install the necessary LangChain packages for integration with Shannon.

```bash
pip install langchain-openai langchain
```

--------------------------------

### Build and Start Shannon Services

Source: https://github.com/kocoro-lab/shannon/blob/main/docs/python-code-execution.md

After updating the configuration, rebuild the `agent-core` and `llm-service` Docker images, then start all services using the provided `make dev` command.

```bash
# Rebuild agent-core with the configuration changes
docker compose -f deploy/compose/docker-compose.yml build --no-cache agent-core

# Rebuild llm-service to include Python executor
docker compose -f deploy/compose/docker-compose.yml build llm-service

# Start all services
make dev
```

--------------------------------

### Install Shannon Python SDK

Source: https://github.com/kocoro-lab/shannon/blob/main/clients/python/README.md

Install the SDK for development or with additional development dependencies.

```bash
pip install -e .

```

```bash
pip install -e ".[dev]"

```

--------------------------------

### Install Development Dependencies

Source: https://github.com/kocoro-lab/shannon/blob/main/docs/ubuntu-quickstart.md

Installs essential development tools and libraries for the Shannon platform on Ubuntu.

```bash
sudo apt-get update && sudo apt-get install -y \
  netcat-traditional curl wget tar unzip git \
  net-tools telnet nmap dnsutils tcpdump \
  htop iotop lsof strace tree jq \
  vim nano grep awk sed \
  build-essential make gcc g++
```

--------------------------------

### Install wabt on Linux (Fedora/RHEL)

Source: https://github.com/kocoro-lab/shannon/blob/main/rust/agent-core/WASI_SETUP.md

Installs the WebAssembly Binary Toolkit (wabt) on Fedora or RHEL-based Linux distributions using dnf.

```bash
# Fedora/RHEL
sudo dnf install wabt
```

--------------------------------

### Install Node Dependencies

Source: https://github.com/kocoro-lab/shannon/blob/main/desktop/desktop-app-windows-build.md

Navigates to the desktop directory and installs all necessary Node.js dependencies for the project.

```powershell
cd desktop
npm install
```

--------------------------------

### Install wabt on Windows using Scoop

Source: https://github.com/kocoro-lab/shannon/blob/main/rust/agent-core/WASI_SETUP.md

Installs the WebAssembly Binary Toolkit (wabt) on Windows using the Scoop package manager.

```powershell
# Option 2: Using Scoop
scoop install wabt
```

--------------------------------

### Set Up Development Environment

Source: https://github.com/kocoro-lab/shannon/blob/main/CONTRIBUTING.md

Run the setup script to create the .env file and generate protobuf files. Add your LLM API key to the .env file. Download the Python WASI interpreter.

```bash
# One-stop setup: creates .env, generates protobuf files
make setup

# Add your LLM API key to .env
echo "OPENAI_API_KEY=your-key-here" >> .env
# Or edit manually: vim .env

# Download Python WASI interpreter for secure code execution (20MB)
./scripts/setup_python_wasi.sh
```

--------------------------------

### Run WASI hello example with cargo

Source: https://github.com/kocoro-lab/shannon/blob/main/rust/agent-core/WASI_SETUP.md

Executes the WASI hello world example using cargo run. This requires navigating to the rust/agent-core directory.

```bash
cd rust/agent-core

# Run the WASI hello example
cargo run --example wasi_hello -- /tmp/hello-wasi.wasm

# Expected output:
# Hello from WASI!
```

--------------------------------

### Full Context Example

Source: https://github.com/kocoro-lab/shannon/blob/main/docs/task-submission-api.md

An example demonstrating the submission of a task with a comprehensive set of parameters including session, mode, model tier, and custom context.

```APIDOC
## POST /api/v1/tasks (Full Context)

### Description
Submits a task with a wide range of parameters, including session ID, mode, model tier, and detailed context.

### Method
POST

### Endpoint
/api/v1/tasks

### Parameters
#### Request Body
- **query** (string) - Required - The main query for the task.
- **session_id** (string) - Optional - Identifier for the session.
- **mode** (string) - Optional - The operational mode (e.g., `"supervisor"`).
- **model_tier** (string) - Optional - The tier of the model to use (e.g., `"large"`).
- **context** (object) - Optional - Detailed context parameters.
  - **role** (string) - Optional - The role for the context (e.g., `"analysis"`).
  - **prompt_params** (object) - Optional - Parameters for prompt customization.
    - **profile_id** (string) - Optional - Profile ID for prompt parameters.
    - **current_date** (string) - Optional - Current date for prompt parameters.

### Request Example
```json
{
  "query": "Summarize our Q3 results",
  "session_id": "sales-2025-q3",
  "mode": "supervisor",
  "model_tier": "large",
  "context": {
    "role": "analysis",
    "prompt_params": {
      "profile_id": "49598h6e",
      "current_date": "2025-10-25"
    }
  }
}
```
```

--------------------------------

### Build and Setup Shannon

Source: https://github.com/kocoro-lab/shannon/blob/main/README.md

Clone the repository, set up the environment, and configure API keys to build the project from source.

```bash
git clone https://github.com/Kocoro-lab/Shannon.git
cd Shannon
make setup                              # Create .env + generate protobuf stubs
vim .env                                # Add your API key
./scripts/setup_python_wasi.sh          # Download Python WASI interpreter
make dev                                # Start all services
make smoke                              # Run E2E smoke tests
```

--------------------------------

### Install Windows Target and Cross-Compilation Tools

Source: https://github.com/kocoro-lab/shannon/blob/main/desktop/desktop-app-windows-build.md

Sets up the Rust environment for cross-compiling to Windows from macOS/Linux by installing the Windows target, Wine, cargo-xwin, and LLVM.

```bash
# Install Windows target
rustup target add x86_64-pc-windows-msvc

# Install Wine (for linking)
brew install wine-stable

# Install cargo-xwin (Windows cross-compilation)
cargo install cargo-xwin

# Install LLVM
brew install llvm
```

--------------------------------

### Get Skill Details API Response Example

Source: https://github.com/kocoro-lab/shannon/blob/main/docs/skills-system.md

Example JSON response for retrieving skill details. It contains comprehensive information about the skill, including its full content and loading metadata.

```json
{
  "skill": {
    "name": "code-review",
    "version": "1.0.0",
    "author": "Shannon",
    "category": "development",
    "description": "Systematic code review workflow",
    "requires_tools": ["file_read", "file_list", "bash"],
    "requires_role": "critic",
    "budget_max": 5000,
    "dangerous": false,
    "enabled": true,
    "content": "# Code Review Skill\n\nYou are performing..."
  },
  "metadata": {
    "source_path": "/app/config/skills/core/code-review.md",
    "content_hash": "abc123...",
    "loaded_at": "2026-01-26T10:00:00Z"
  }
}
```

--------------------------------

### Install buf CLI Tool

Source: https://github.com/kocoro-lab/shannon/blob/main/scripts/README.md

Installs the `buf` CLI tool for protobuf management if it's missing. This is often called by `make proto`.

```bash
chmod +x script_name.sh
```

--------------------------------

### Build and Install iOS App on Device

Source: https://github.com/kocoro-lab/shannon/blob/main/desktop/desktop-app-ios-build.md

Use these commands to build the iOS app for a device and install it directly. Ensure your iPhone is connected and trusted.

```bash
cd desktop
npm run tauri ios build -- --target aarch64

# 2. Connect iPhone via USB and trust the computer

# 3. List connected devices
xcrun devicectl list devices

# 4. Install directly to device (replace DEVICE_ID)
xcrun devicectl device install app --device DEVICE_ID \
  ~/Library/Developer/Xcode/DerivedData/app-*/Build/Products/release-iphoneos/shannon-desktop.app
```

--------------------------------

### Setup and Run Shannon Project

Source: https://github.com/kocoro-lab/shannon/blob/main/CLAUDE.md

Essential commands for setting up, configuring, and running the Shannon project locally. Includes commands for setup, development, testing, and proto file regeneration.

```bash
make setup && vim .env && make dev
```

```bash
make smoke
```

```bash
make proto
```

```bash
make ci
```

--------------------------------

### TOOL_INVOKED Event Example

Source: https://github.com/kocoro-lab/shannon/blob/main/docs/event-types.md

Indicates that a tool or function execution has started. May include sanitized parameters.

```json
{
  "type": "TOOL_INVOKED",
  "agent_id": "data-agent",
  "message": "Calling database_query with table=users",
  "seq": 10
}
```

--------------------------------

### Install Protocol Buffers Compiler (protoc)

Source: https://github.com/kocoro-lab/shannon/blob/main/docs/rocky-linux-quickstart.md

Installs the Protocol Buffers compiler by downloading the binary, extracting it, and placing it in the system path. Includes copying include files for proper functionality.

```bash
# Download official protoc binary
cd /tmp
curl -LO https://github.com/protocolbuffers/protobuf/releases/download/v24.4/protoc-24.4-linux-x86_64.zip

# Extract and install
unzip -o protoc-24.4-linux-x86_64.zip
mv bin/protoc /usr/local/bin/
chmod +x /usr/local/bin/protoc
ln -s /usr/local/bin/protoc /usr/bin/

# Copy include files
cp -r /tmp/include/google /usr/local/include/
```

--------------------------------

### AGENT_STARTED Event Example

Source: https://github.com/kocoro-lab/shannon/blob/main/docs/event-types.md

Signals that an agent has begun processing a task. The `agent_id` specifies which agent is starting.

```json
{
  "type": "AGENT_STARTED",
  "agent_id": "simple-agent",
  "message": "Processing query",
  "seq": 7
}
```

--------------------------------

### Get Task Status API Response (Completed)

Source: https://github.com/kocoro-lab/shannon/blob/main/docs/browser-automation-api.md

Example response for a completed task, including results and metadata.

```json
{
  "task_id": "task-xxx-1234567890",
  "status": "TASK_STATUS_COMPLETED",
  "result": "The extracted content or summary...",
  "metadata": {
    "iterations": 3,
    "actions": 4,
    "observations": 3
  }
}
```

--------------------------------

### Tool Execution Commands

Source: https://github.com/kocoro-lab/shannon/blob/main/docs/adding-custom-tools.md

Examples of how to interact with the Shannon tools API via cURL, including listing tools, getting schemas, and executing tools.

```bash
# List tools
curl http://localhost:8000/tools/list

# Get schema
curl http://localhost:8000/tools/{name}/schema

# Execute
curl -X POST http://localhost:8000/tools/execute \
  -d '{"tool_name":"my_tool","parameters":{...}}'
```

--------------------------------

### Quick Start: Run All Tests

Source: https://github.com/kocoro-lab/shannon/blob/main/tests/README_E2E_TESTS.md

Execute all end-to-end tests from the tests directory.

```bash
cd /Users/wayland/Code_Ptmind/Shannon/tests

# Run all tests
./run_all_e2e_tests.sh
```

--------------------------------

### GitHub Actions: Run E2E Tests

Source: https://github.com/kocoro-lab/shannon/blob/main/tests/README_E2E_TESTS.md

Example GitHub Actions workflow to check out code, start Shannon services, wait for them, and run the E2E tests.

```yaml
name: E2E Tests
on: [push, pull_request]

jobs:
  e2e:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Start Shannon Services
        run: make dev
      - name: Wait for Services
        run: sleep 30
      - name: Run E2E Tests
        run: cd tests && ./run_all_e2e_tests.sh
```

--------------------------------

### Start Shannon Services with Make

Source: https://github.com/kocoro-lab/shannon/blob/main/tests/README_E2E_TESTS.md

Initiate all necessary Shannon services using the 'make dev' command.

```bash
# From Shannon project root
make dev
```

--------------------------------

### Manage Sessions

Source: https://github.com/kocoro-lab/shannon/blob/main/go/orchestrator/cmd/gateway/README.md

Provides examples for session management, including listing all sessions, retrieving session details, fetching conversation history, and getting session events.

```bash
# List all sessions for a user
curl -s -H "X-API-Key: $API_KEY" \
  "http://localhost:8080/api/v1/sessions?limit=20&offset=0"

# Get session details
curl -s -H "X-API-Key: $API_KEY" \
  "http://localhost:8080/api/v1/sessions/$SESSION_ID" | jq

# Get conversation history for a session
curl -s -H "X-API-Key: $API_KEY" \
  "http://localhost:8080/api/v1/sessions/$SESSION_ID/history" | jq

# Get session events (excludes partial LLM responses)
curl -s -H "X-API-Key: $API_KEY" \
  "http://localhost:8080/api/v1/sessions/$SESSION_ID/events?limit=100" | jq
```

--------------------------------

### Query Per-Task Historical Events API

Source: https://github.com/kocoro-lab/shannon/blob/main/docs/event-types.md

Example of a GET request to retrieve historical events for a specific task. Supports pagination with 'limit' and 'offset' parameters.

```bash
GET /api/v1/tasks/{id}/events?limit=50&offset=0
```

--------------------------------

### Quick Start Test Commands

Source: https://github.com/kocoro-lab/shannon/blob/main/docs/testing.md

Run all unit tests, start the development environment, execute smoke tests, or run end-to-end scenarios using these make targets and scripts.

```bash
# 1. Run all unit tests
make test

# 2. Start the full stack
make dev

# 3. Run smoke test (health, gRPC, persistence, metrics)
make smoke

# 4. Run E2E scenarios
tests/e2e/run.sh
```

--------------------------------

### WebSocket Stream Real-Time Events API

Source: https://github.com/kocoro-lab/shannon/blob/main/docs/event-types.md

Example of a GET request to stream real-time events via WebSocket. Similar to SSE, use query parameters for filtering and resuming.

```bash
GET /stream/ws?workflow_id={id}&types={csv}&last_event_id={id-or-seq}
```

--------------------------------

### Setup Remote Server and Generate Proto

Source: https://github.com/kocoro-lab/shannon/blob/main/docs/rocky-linux-quickstart.md

Execute these scripts to set up the remote server and generate the necessary proto files for cross-language gRPC communication.

```bash
./scripts/setup-remote.sh
```

```bash
make proto
```

--------------------------------

### Interact with Shannon using Python SDK

Source: https://github.com/kocoro-lab/shannon/blob/main/README.md

Install the Shannon Python SDK to programmatically interact with Shannon agents. This example shows how to submit a task, wait for its completion, and retrieve the result.

```bash
pip install shannon-sdk
```

```python
from shannon import ShannonClient

with ShannonClient(base_url="http://localhost:8080") as client:
    handle = client.submit_task("What is the capital of France?", session_id="demo")
    result = client.wait(handle.task_id)
    print(result.result)
```

--------------------------------

### Makefile: Setup Environment

Source: https://github.com/kocoro-lab/shannon/blob/main/docs/environment-configuration.md

This Makefile target, `setup-env`, checks if a `.env` file exists. If not, it copies `.env.example` to `.env` and prompts the user to edit it. It then ensures the symlink to the correct `.env` file is in place within the `deploy/compose` directory.

```makefile
# Setup environment
.PHONY: setup-env
setup-env:
	@if [ ! -f .env ]; then \
		cp .env.example .env; \
		echo "Created .env file - please edit with your API keys"; \
	fi
	@cd deploy/compose && ln -sf ../../.env .env
	@echo "Environment setup complete"
```

--------------------------------

### Query Session Historical Events API

Source: https://github.com/kocoro-lab/shannon/blob/main/docs/event-types.md

Example of a GET request to retrieve historical events for a session, excluding LLM_PARTIAL events. Supports pagination and returns a 404 if the session is soft-deleted.

```bash
GET /api/v1/sessions/{sessionId}/events?limit=200&offset=0
```

--------------------------------

### Chat Completion (Node.js)

Source: https://github.com/kocoro-lab/shannon/blob/main/docs/openai-api-reference.md

This Node.js example demonstrates how to use the OpenAI SDK to interact with the Shannon API for chat completions. Ensure you have the 'openai' package installed and replace 'sk-shannon-your-api-key' with your actual API key.

```javascript
import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'sk-shannon-your-api-key',
  baseURL: 'https://api.shannon.run/v1'
});

async function main() {
  const completion = await client.chat.completions.create({
    model: 'shannon-deep-research',
    messages: [{ role: 'user', content: 'Research AI trends' }]
  });
  console.log(completion.choices[0].message.content);
}

main();
```

--------------------------------

### Sequential Pipeline Example

Source: https://github.com/kocoro-lab/shannon/blob/main/docs/p2p-coordination.md

Shannon automatically detects sequential dependencies, such as Task 2 consuming data produced by Task 1. Task 2 will wait for Task 1 to complete before starting execution.

```python
# Query: "Analyze sales data and then create a report based on the analysis"

# Shannon automatically detects:
# - Task 1: Analyze → produces: ["sales-analysis", "insights"]
# - Task 2: Report → consumes: ["sales-analysis", "insights"]
#
# Task 2 waits for Task 1 to complete before starting
```

--------------------------------

### Initialize Shannon Platform

Source: https://github.com/kocoro-lab/shannon/blob/main/docs/ubuntu-quickstart.md

Executes commands to set up the Shannon environment, generate gRPC code, and start the development server. Initial startup may take several minutes.

```bash
make setup-env

./scripts/setup-remote.sh

make proto

make dev
```

--------------------------------

### Initialize Template Registry and Load Templates in Go

Source: https://github.com/kocoro-lab/shannon/blob/main/docs/templates.md

Demonstrates how to initialize a template registry using `workflows.InitTemplateRegistry` and load templates from a specified directory. Error handling is included.

```go
// Load templates from directory
registry, err := workflows.InitTemplateRegistry(logger, "/path/to/templates")
```

--------------------------------

### Run Shannon Gateway with Docker Compose

Source: https://github.com/kocoro-lab/shannon/blob/main/go/orchestrator/cmd/gateway/README.md

Build and start all services using Docker Compose. Authentication is disabled by default for easy setup. Includes commands to submit a task, check health, and view the OpenAPI specification.

```bash
# Build and start all services (auth disabled by default for easy start)
docker compose -f deploy/compose/docker-compose.yml up -d

# Submit your first task - no API key needed!
curl -X POST http://localhost:8080/api/v1/tasks \
  -H "Content-Type: application/json" \
  -d '{"query":"What is 2+2?"}'

# Check gateway health
curl http://localhost:8080/health

# View OpenAPI specification
curl http://localhost:8080/openapi.json | jq
```

--------------------------------

### SSE Stream Real-Time Events API

Source: https://github.com/kocoro-lab/shannon/blob/main/docs/event-types.md

Example of a GET request to stream real-time events via Server-Sent Events (SSE). Use query parameters to filter by workflow ID, event types, and last event ID for resuming streams.

```bash
GET /stream/sse?workflow_id={id}&types={csv}&last_event_id={id-or-seq}
```

--------------------------------

### Start Shannon Platform

Source: https://github.com/kocoro-lab/shannon/blob/main/docs/rocky-linux-quickstart.md

Use this command to start the complete Shannon platform. Initial startup may take several minutes due to Docker image downloads.

```bash
make dev
```

--------------------------------

### List, Get, Update, Pause, Resume, and Delete Schedules

Source: https://github.com/kocoro-lab/shannon/blob/main/clients/python/README.md

Provides examples for managing schedules, including listing active schedules, retrieving details of a specific schedule, updating its cron expression and budget, pausing and resuming it, and finally deleting it. Requires an initialized `ShannonClient`.

```python
# List all active schedules
schedules, total = client.list_schedules(status="ACTIVE")
print(f"Found {total} active schedules")

for s in schedules:
    print(f"  {s.name}: {s.cron_expression} (next: {s.next_run_at})")

# Get schedule details
schedule = client.get_schedule("schedule-id")
print(f"Schedule: {schedule.name}")
print(f"Status: {schedule.status}")
print(f"Runs: {schedule.total_runs} total, {schedule.successful_runs} succeeded, {schedule.failed_runs} failed")

# Update schedule
client.update_schedule(
    "schedule-id",
    cron_expression="0 10 * * 1-5",  # Change to 10am
    max_budget_per_run_usd=1.00,
)

# Pause/resume
client.pause_schedule("schedule-id", reason="Holiday break")
client.resume_schedule("schedule-id", reason="Back from holiday")

# Delete
client.delete_schedule("schedule-id")
```

--------------------------------

### Build and Run Docker Image

Source: https://github.com/kocoro-lab/shannon/blob/main/python/llm-service/README.md

Instructions for building the Docker image for the LLM service and running it. Running with `make dev` is recommended for a development setup.

```bash
# Build image
docker build -t shannon-llm-service .

# Run with compose (recommended)
make dev  # From repository root

# Or run standalone
docker run -p 8000:8000 \
  -e OPENAI_API_KEY=$OPENAI_API_KEY \
  shannon-llm-service
```

--------------------------------

### NSIS Installer Usage

Source: https://github.com/kocoro-lab/shannon/blob/main/desktop/desktop-app-windows-build.md

Shows how to run the NSIS installer, perform a silent installation, or specify a custom installation directory.

```powershell
# Run installer
shannon-desktop_0.1.0_x64-setup.exe

# Silent install
shannon-desktop_0.1.0_x64-setup.exe /S

# Custom install directory
shannon-desktop_0.1.0_x64-setup.exe /D=C:\Custom\Path
```

--------------------------------

### Backward Compatible Subscription Example

Source: https://github.com/kocoro-lab/shannon/blob/main/docs/streaming-manager-improvements.md

Demonstrates that existing code for subscribing and unsubscribing to streams remains functional after the improvements. This ensures a smooth migration path with no breaking changes.

```go
// Old code still works:
ch := streaming.Get().Subscribe("workflow-123", 100)
deferr streaming.Get().Unsubscribe("workflow-123", ch)

for evt := range ch {
    // Process events
}
```

--------------------------------

### Install WiX Toolset

Source: https://github.com/kocoro-lab/shannon/blob/main/desktop/desktop-app-windows-build.md

Install the WiX Toolset, required for building MSI installers, either via Chocolatey or by downloading the installer from the official WiX Toolset releases page.

```powershell
# Install WiX Toolset for MSI builds
# https://wixtoolset.org/releases/

# Or via Chocolatey
choco install wixtoolset
```

--------------------------------

### Complete Task Execution Example in Rust

Source: https://github.com/kocoro-lab/shannon/blob/main/docs/agent-core-api.md

Demonstrates how to connect to the agent service, prepare and execute a task request, and process the response, including checking metrics.

```rust
use shannon_agent_core::grpc_server::proto::agent::*;
use tonic::Request;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Connect to agent
    let mut client = agent_service_client::AgentServiceClient::connect(
        "http://localhost:50051"
    ).await?;
    
    // Prepare request
    let request = Request::new(ExecuteTaskRequest {
        query: "Search for the latest Rust programming news and summarize it".to_string(),
        mode: ExecutionMode::Standard as i32,
        available_tools: vec![
            "web_search".to_string(),
            "calculator".to_string(),
        ],
        config: Some(AgentConfig {
            max_iterations: 5,
            timeout_seconds: 30,
            enable_sandbox: true,
            memory_limit_mb: 256,
            enable_learning: false,
        }),
        session_context: Some(SessionContext {
            session_id: "user-123".to_string(),
            history: vec![
                "User: What is Rust?".to_string(),
                "Agent: Rust is a systems programming language...".to_string(),
            ],
            total_tokens_used: 1500,
            total_cost_usd: 0.003,
            ..Default::default()
        }),
        ..Default::default()
    });
    
    // Execute task
    let response = client.execute_task(request).await?;
    let response = response.into_inner();
    
    // Process response
    println!("Task ID: {}", response.task_id);
    println!("Status: {:?}", response.status);
    println!("Result: {}", response.result);
    
    // Check metrics
    if let Some(metrics) = response.metrics {
        println!("Tokens used: {}", metrics.token_usage.as_ref().unwrap().total_tokens);
        println!("Execution time: {}ms", metrics.latency_ms);
    }
    
    Ok(())
}
```

--------------------------------

### Install Build Tools Manually

Source: https://github.com/kocoro-lab/shannon/blob/main/clients/python/PACKAGING.md

Manually installs the 'build' and 'twine' packages if not installed via development dependencies.

```bash
pip install build twine
```

--------------------------------

### Initialize Shannon Project Environment

Source: https://github.com/kocoro-lab/shannon/blob/main/docs/rocky-linux-quickstart.md

Executes the make setup-env command to initialize the project environment and basic configuration for the Shannon platform.

```bash
# Step 1: Initialize project environment and basic configuration
make setup-env
```

--------------------------------

### Install Node.js Dependencies and Verify Tauri

Source: https://github.com/kocoro-lab/shannon/blob/main/desktop/desktop-app-build-guide.md

Installs Node.js dependencies for the desktop app and verifies the Tauri CLI installation.

```bash
cd desktop
npm install

npm run tauri -- version
```

--------------------------------

### Install CocoaPods via Homebrew

Source: https://github.com/kocoro-lab/shannon/blob/main/desktop/desktop-app-ios-build.md

Use Homebrew to install CocoaPods to resolve installation errors that may occur when using gem.

```bash
brew install cocoapods
```

--------------------------------

### Build and Run Orchestrator Binary (Go)

Source: https://github.com/kocoro-lab/shannon/blob/main/go/orchestrator/README.md

Builds the orchestrator executable and runs it locally. Requires prerequisite services (PostgreSQL, Redis, Temporal) to be running.

```bash
go build -o orchestrator .

./orchestrator
```

--------------------------------

### Configure Environment Variables

Source: https://github.com/kocoro-lab/shannon/blob/main/docs/ubuntu-quickstart.md

Copies the example environment file and prompts to edit it. Essential API keys for LLM and search services should be configured here.

```bash
cp .env.example .env

vi .env
```

--------------------------------

### Install NSIS Compiler

Source: https://github.com/kocoro-lab/shannon/blob/main/desktop/desktop-app-windows-build.md

Install the NSIS (Nullsoft Scriptable Install System) compiler using Chocolatey or by downloading it directly from the official website.

```powershell
# Install NSIS
choco install nsis

# Or download from https://nsis.sourceforge.io/
```

--------------------------------

### MSI Installer Usage

Source: https://github.com/kocoro-lab/shannon/blob/main/desktop/desktop-app-windows-build.md

Provides commands for standard, silent, and silent uninstallation of the MSI Windows installer. Requires the full installer filename.

```powershell
# Standard install
shannon-desktop_0.1.0_x64_en-US.msi

# Silent install
msiexec /i shannon-desktop_0.1.0_x64_en-US.msi /quiet /norestart

# Silent uninstall
msiexec /x shannon-desktop_0.1.0_x64_en-US.msi /quiet
```

--------------------------------

### List All Available Templates in Registry in Go

Source: https://github.com/kocoro-lab/shannon/blob/main/docs/templates.md

Demonstrates how to retrieve a list of all available template summaries from the registry.

```go
// List all templates
summaries := registry.List()
```

--------------------------------

### User Installation with Specific Version

Source: https://github.com/kocoro-lab/shannon/blob/main/docs/release-process.md

Install Shannon by specifying the desired version using the SHANNON_VERSION environment variable. This allows users to install older releases if needed.

```bash
curl -fsSL https://raw.githubusercontent.com/Kocoro-lab/Shannon/main/scripts/install.sh | SHANNON_VERSION=v0.4.0 bash
```

--------------------------------

### Install Visual Studio Build Tools

Source: https://github.com/kocoro-lab/shannon/blob/main/desktop/desktop-app-windows-build.md

Install the necessary C++ build tools for Visual Studio. Ensure the 'Desktop development with C++' workload is selected during installation.

```powershell
# Install Visual Studio Build Tools
# https://visualstudio.microsoft.com/downloads/
# Select "Desktop development with C++" workload
```

--------------------------------

### Quick Start: Run Individual Test Suite

Source: https://github.com/kocoro-lab/shannon/blob/main/tests/README_E2E_TESTS.md

Execute a specific end-to-end test suite, such as the comprehensive system test.

```bash
./e2e/comprehensive_system_test.sh
```

--------------------------------

### DiscoverTools gRPC Request Example (Rust)

Source: https://github.com/kocoro-lab/shannon/blob/main/docs/agent-core-api.md

Shows how to use the gRPC client to discover available tools. Filters can be applied to narrow down the search results.

```rust
let request = DiscoverToolsRequest {
    query: "search".to_string(),
    exclude_dangerous: true,
    max_results: 5,
    ..Default::default()
};

let response = client.discover_tools(request).await?;
for tool in response.tools {
    println!("Found tool: {} - {}", tool.name, tool.description);
}
```

--------------------------------

### Build Tauri Installers (MSI and NSIS)

Source: https://github.com/kocoro-lab/shannon/blob/main/desktop/desktop-app-windows-build.md

Builds all available installer types for the Tauri application, including MSI and NSIS. Specific installer types can be built using the --bundles flag.

```powershell
# Build all installer types (MSI + NSIS)
npm run tauri:build
```

```powershell
# Build specific installer type
npm run tauri:build -- --bundles msi      # MSI only
npm run tauri:build -- --bundles nsis     # NSIS only
```

--------------------------------

### Runtime Registration Response

Source: https://github.com/kocoro-lab/shannon/blob/main/docs/adding-custom-tools.md

Example response after successfully registering a tool at runtime, confirming registration details.

```json
{
  "success": true,
  "collection_name": "petstore",
  "operations_registered": ["getPetById", "findPetsByStatus"],
  "rate_limit": 15,
  "timeout_seconds": 10,
  "max_response_bytes": 10485760
}
```

--------------------------------

### Vendor Adapter Project Structure and Testing

Source: https://github.com/kocoro-lab/shannon/blob/main/docs/vendor-adapters.md

Illustrates the typical file structure for a vendor adapter integration and provides commands for building and testing the service.

```bash
# Structure
config/overlays/shannon.myvendor.yaml
config/openapi_specs/myvendor_api.yaml
python/llm-service/llm_service/tools/vendor_adapters/myvendor.py
python/llm-service/llm_service/roles/myvendor/my_agent.py

# Environment
SHANNON_CONFIG_PATH=config/overlays/shannon.myvendor.yaml
MYVENDOR_API_TOKEN=your_token

# Test
docker compose build --no-cache llm-service orchestrator
docker compose up -d
./scripts/submit_task.sh "Your query here"
```