mentor

Work agents for Daedalus — powered by Pallas.

Mentor is a pure agent project: Python agent definitions + YAML configuration. The runtime (serving, registry, health checks, multimodal support) lives in Pallas.

Architecture

Daedalus Backend — FastAPI
    │  MCP over StreamableHTTP
    ▼
Pallas MCP Bridge (pallas.server:main)
    │  reads agents.yaml for topology
    │  reads fastagent.config.yaml for LLM + model capabilities
    │
    ├── Registry    → /.well-known/mcp/server.json (agent discovery)
    ├── Jarvis      → kernos, rommie, argos, neo4j_cypher, athena, time
    ├── Jeffrey     → neo4j_cypher, athena, research, time
    ├── Ann         → research, argos, neo4j_cypher, athena, angelia, time
    ├── Alan        → research, argos, athena, neo4j_cypher, time
    ├── AWS SA      → aws_knowledge, aws_docs, aws_pricing, argos, context7
    ├── Research    → argos, neo4j_cypher
    └── Tech Research → context7, github, argos

Project Structure

.
├── agents.yaml              # Deployment topology — agents, ports, host, namespace
├── fastagent.config.yaml    # LLM provider, MCP servers, model capabilities (committed)
├── fastagent.secrets.yaml   # API keys and tokens (gitignored — never commit)
├── agents/                  # Agent definitions (FastAgent @fast.agent decorators)
│   ├── jarvis.py
│   ├── jeffrey.py
│   ├── ann.py
│   ├── alan.py
│   ├── aws_sa.py
│   ├── research.py
│   └── tech_research.py
├── systemd/
│   └── mentor.service
├── pyproject.toml
└── .env.example

Configuration

`agents.yaml` — Deployment Topology

Single source of truth for agent names, ports, dependencies, host, and namespace. Read by Pallas at startup.

name: mentor
version: "1.0.0"
host: puck.incus
namespace: ca.helu.mentor
registry_port: 24200

agents:
  jarvis:
    module: agents.jarvis
    port: 24201
    title: Jarvis
    description: "Work execution assistant — task management, meetings, daily operations"
    depends_on: [research]
  # ...

To deploy a different agent group, swap agents.yaml — no code changes needed. Override the config path with PALLAS_AGENTS_CONFIG env var.

`fastagent.config.yaml` — LLM + Model Capabilities

Committed to the repo. Contains LLM provider settings and explicit model capability declarations.

default_model: openai.global.anthropic.claude-opus-4-6-v1

model_capabilities:
  vision: false
  context_window: 200000
  max_output_tokens: 32000

The model_capabilities section declares capabilities explicitly rather than inferring from the model name. Exposed in the registry for Daedalus to use when routing requests (e.g., vision-capable agents).

`fastagent.secrets.yaml` — API Keys and Tokens

Gitignored — never commit. Place in the repo root alongside fastagent.config.yaml.

openai:
  api_key: "your-key-here"

mcp:
  servers:
    angelia:
      headers:
        Authorization: "Bearer your-token"
    # ...

Quickstart

Prerequisites

Python 3.13+ (fast-agent-mcp pins >=3.13)
Node.js / npm — for the context7 stdio MCP server (npx -y @upstash/context7-mcp)
Docker — for the github stdio MCP server
uv / uvx at /usr/local/bin/uvx — required by the aws_docs and aws_pricing stdio MCP servers. fast-agent's stdio client sanitizes PATH before spawning subprocesses (via mcp.client.stdio.get_default_environment()), so fastagent.config.yaml references uvx by absolute path. Install system-wide — this matches the Ansible production deploy (virgo/ansible/mentor/deploy.yml) so dev and prod configs are identical:
```
sudo sh -c 'curl -LsSf https://astral.sh/uv/install.sh | env UV_INSTALL_DIR=/usr/local/bin sh'
```
Do not use the default per-user install (~/.local/bin/uvx) — the config will not find it at runtime under systemd or under pallas' sanitized PATH.

# 1. Install dependencies (Python 3.13 required)
source ~/env/mentor/bin/activate
pip install -e .

# 2. Configure secrets
cp fastagent.secrets.yaml.example fastagent.secrets.yaml
# Edit: set api_key and service tokens

# 3. Start all agents
mentor

# 4. Verify
curl http://localhost:24201/mcp

# 5. Start a single agent
mentor --agent jarvis

Daedalus Integration

Daedalus connects to agents via the MCP Python SDK's streamable_http_client.

Registry endpoint: http://<host>:<registry_port>/.well-known/mcp/server.json

The registry includes model capabilities on each agent entry:

{
  "capabilities": {
    "model": "global.anthropic.claude-opus-4-6-v1",
    "vision": false,
    "context_window": 200000,
    "max_output_tokens": 32000
  }
}

Deployment (systemd)

# 1. Copy project to /srv/mentor
sudo cp -r . /srv/mentor
sudo chown -R mentor:mentor /srv/mentor

# 2. Install into venv
cd /srv/mentor
source ~/env/mentor/bin/activate
pip install -e .

# 3. Configure secrets
cp fastagent.secrets.yaml.example fastagent.secrets.yaml
# Fill in API keys and tokens

# 4. Install and start systemd service
sudo cp systemd/mentor.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now mentor
sudo systemctl status mentor

Downstream MCP Servers

Server	Host	URL
argos	miranda.incus	`http://miranda.incus:25534/mcp`
neo4j_cypher	circe.helu.ca	`http://circe.helu.ca:22034/mcp`
kernos	caliban.incus	`http://caliban.incus:22021/mcp`
rommie	caliban.incus	`http://caliban.incus:22031/mcp`
gitea	miranda.incus	`http://miranda.incus:25535/mcp`
grafana	miranda.incus	`http://miranda.incus:25533/mcp`
angelia	ouranos.helu.ca	`https://ouranos.helu.ca/mcp/`
athena	ouranos.helu.ca	`https://athena.ouranos.helu.ca/mcp/`
kairos	ouranos.helu.ca	`https://kairos.ouranos.helu.ca/mcp/`
github	local (Docker stdio)	`ghcr.io/github/github-mcp-server`
context7	local (stdio)	`npx -y @upstash/context7-mcp`
time	local (stdio)	`mcp-server-time`
aws_knowledge	knowledge-mcp.global.api.aws	`https://knowledge-mcp.global.api.aws`
aws_docs	local (stdio)	`uvx awslabs.aws-documentation-mcp-server@latest`
aws_pricing	local (stdio)	`uvx awslabs.aws-pricing-mcp-server@latest`

Notes

Python 3.13 required (fast-agent-mcp pins >=3.13)
Runtime: Pallas — pallas-mcp @ git+ssh://git@git.helu.ca:22022/r/pallas.git
Transport: StreamableHTTP (/mcp) throughout — not SSE
Logging: Console output — stdout → syslog → Alloy → Loki in production
Port scheme: registry at registry_port, agents at configured ports in agents.yaml

6.8 KiB Raw Blame History