Initial commit: pallas package extracted from mentor

2026-04-02 12:41:53 +00:00
commit 9092afb532
8 changed files with 1094 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,114 @@
+# Pallas — FastAgent MCP Bridge
+
+Pallas is the generic runtime that turns [fast-agent](https://github.com/evalstate/fast-agent) agent definitions into StreamableHTTP MCP servers.
+
+It is **completely deployment-agnostic**: all environment-specific values (agent names, ports, hosts, model) live in the calling project's `agents.yaml` and `fastagent.config.yaml`.
+
+---
+
+## Installation
+
+```bash
+pip install git+ssh://git@git.helu.ca:22022/r/pallas.git
+```
+
+Or as a project dependency in `pyproject.toml`:
+
+```toml
+dependencies = [
+    "pallas-mcp @ git+ssh://git@git.helu.ca:22022/r/pallas.git",
+]
+```
+
+---
+
+## Usage
+
+Pallas reads configuration from the **working directory** at runtime.
+
+```
+my-project/
+├── agents/
+│   ├── __init__.py
+│   └── jarvis.py          # FastAgent definitions
+├── agents.yaml            # Deployment topology
+├── fastagent.config.yaml  # FastAgent + model config
+└── fastagent.secrets.yaml # API keys (gitignored)
+```
+
+Run from your project root:
+
+```bash
+pallas                     # start all agents + registry
+pallas --agent jarvis      # start a single agent
+```
+
+Or via `python -m`:
+
+```bash
+python -m pallas.server
+```
+
+---
+
+## `agents.yaml` format
+
+```yaml
+name: my-project           # used in log prefixes and registry names
+version: "1.0.0"
+host: my-host.example.com  # hostname for registry URLs
+namespace: com.example.my-project
+registry_port: 8200
+
+agents:
+  jarvis:
+    module: agents.jarvis  # importable Python module path
+    port: 8201
+    title: Jarvis
+    description: "My assistant agent"
+    depends_on: [research]  # optional: start these first
+
+  research:
+    module: agents.research
+    port: 8250
+    title: Research Agent
+    description: "Web search and knowledge graph"
+```
+
+---
+
+## `fastagent.config.yaml` extensions
+
+Pallas reads two extra keys beyond the standard fast-agent config:
+
+```yaml
+default_model: openai.my-custom-model-name
+
+# Explicit capability declarations — avoids brittle name-regex heuristics
+model_capabilities:
+  vision: false
+  context_window: 200000
+  max_output_tokens: 32000
+```
+
+Capabilities are published in the registry and used to register unknown models
+with fast-agent's `ModelDatabase`.
+
+---
+
+## Environment variable
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `PALLAS_AGENTS_CONFIG` | `agents.yaml` | Override path to deployment config |
+
+---
+
+## What Pallas provides
+
+| Module | Purpose |
+|---|---|
+| `pallas.server` | CLI entry point and agent orchestration |
+| `pallas.registry` | `GET /.well-known/mcp/server.json` registry server |
+| `pallas.multimodal_server` | `MultimodalAgentMCPServer` — `AgentMCPServer` subclass with image support |
+| `pallas.health` | LLM preflight validation + `get_health` MCP tool |