219 lines
6.8 KiB
Markdown
219 lines
6.8 KiB
Markdown
# mentor
|
|
|
|
Work agents for Daedalus — powered by [Pallas](https://git.helu.ca/r/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.
|
|
|
|
```yaml
|
|
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.
|
|
|
|
```yaml
|
|
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`.
|
|
|
|
```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:
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```json
|
|
{
|
|
"capabilities": {
|
|
"model": "global.anthropic.claude-opus-4-6-v1",
|
|
"vision": false,
|
|
"context_window": 200000,
|
|
"max_output_tokens": 32000
|
|
}
|
|
}
|
|
```
|
|
|
|
## Deployment (systemd)
|
|
|
|
```bash
|
|
# 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](https://git.helu.ca/r/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`
|