docs: add README for every content directory
Each directory (agents, hands, integrations, plugins, providers, scripts, skills) now has a README documenting its TOML format, current contents, and contribution steps.
This commit is contained in:
Evan Hu committed
1 parent
d1bc8ead69
commit
206169c1d7
7 files changed
+448
No files matched your search
@@ -0,0 +1,63 @@
|
||||
# Agents
|
||||
|
||||
Autonomous agent definitions for LibreFang. Each agent is a directory containing an `agent.toml` manifest.
|
||||
|
||||
## Structure
|
||||
|
||||
```
|
||||
agents/
|
||||
├── hello-world/agent.toml
|
||||
├── researcher/agent.toml
|
||||
├── coder/agent.toml
|
||||
└── ...
|
||||
```
|
||||
|
||||
## agent.toml Format
|
||||
|
||||
```toml
|
||||
name = "agent-name" # Must match directory name
|
||||
version = "0.1.0"
|
||||
description = "What this agent does"
|
||||
author = "author-name"
|
||||
module = "builtin:chat" # Runtime module
|
||||
|
||||
[model]
|
||||
provider = "default"
|
||||
model = "default"
|
||||
max_tokens = 4096
|
||||
temperature = 0.7
|
||||
system_prompt = """Behavioral instructions for the agent."""
|
||||
|
||||
[metadata.routing]
|
||||
aliases = ["exact match phrases"]
|
||||
weak_aliases = ["keyword hints"]
|
||||
|
||||
[resources]
|
||||
max_llm_tokens_per_hour = 100000
|
||||
|
||||
[capabilities]
|
||||
tools = ["web_search", "file_read"]
|
||||
network = ["*"]
|
||||
memory_read = ["*"]
|
||||
memory_write = ["self.*"]
|
||||
agent_spawn = false
|
||||
```
|
||||
|
||||
## Current Agents (33)
|
||||
|
||||
| Agent | Description |
|
||||
|-------|-------------|
|
||||
| assistant | Default conversational assistant |
|
||||
| researcher | Deep research with web search |
|
||||
| coder | Code generation and editing |
|
||||
| hello-world | Friendly greeting agent for new users |
|
||||
| ... | See each directory for details |
|
||||
|
||||
## Adding a New Agent
|
||||
|
||||
1. Create `agents/<name>/agent.toml`
|
||||
2. Ensure `name` matches the directory name
|
||||
3. Run `python scripts/validate.py`
|
||||
4. Submit a PR
|
||||
|
||||
See [CONTRIBUTING.md](../CONTRIBUTING.md) for the full guide.
|
||||
@@ -0,0 +1,74 @@
|
||||
# Hands
|
||||
|
||||
Hand definitions for LibreFang. Hands are the user-facing "apps" -- higher-level application bundles that package an agent with tools, settings, dashboard metrics, and dependency requirements.
|
||||
|
||||
> "You have many hands helping you." -- Hands are how LibreFang users interact with specialized capabilities.
|
||||
|
||||
## Structure
|
||||
|
||||
```
|
||||
hands/
|
||||
├── browser/
|
||||
│ ├── HAND.toml # Hand definition
|
||||
│ └── SKILL.md # Documentation
|
||||
├── trader/
|
||||
│ ├── HAND.toml
|
||||
│ └── SKILL.md
|
||||
└── ...
|
||||
```
|
||||
|
||||
## HAND.toml Format
|
||||
|
||||
```toml
|
||||
id = "hand-id" # Must match directory name
|
||||
name = "Hand Name"
|
||||
description = "What this hand does"
|
||||
category = "productivity" # communication | content | data | development |
|
||||
# devops | finance | productivity | research | social
|
||||
icon = "🔧"
|
||||
tools = ["tool1", "tool2"]
|
||||
|
||||
[routing]
|
||||
aliases = ["activate phrases"]
|
||||
weak_aliases = ["keyword hints"]
|
||||
|
||||
[[requires]] # External dependencies
|
||||
key = "python3"
|
||||
requirement_type = "binary"
|
||||
check_value = "python3"
|
||||
|
||||
[[settings]] # User-configurable options
|
||||
key = "headless"
|
||||
setting_type = "toggle"
|
||||
default = "true"
|
||||
|
||||
[agent] # The agent powering this hand
|
||||
name = "hand-agent"
|
||||
module = "builtin:chat"
|
||||
system_prompt = """..."""
|
||||
|
||||
[dashboard] # Dashboard metrics
|
||||
[[dashboard.metrics]]
|
||||
label = "Tasks Completed"
|
||||
memory_key = "metric_key"
|
||||
format = "number"
|
||||
```
|
||||
|
||||
## Current Hands (14)
|
||||
|
||||
| Hand | Category | Description |
|
||||
|------|----------|-------------|
|
||||
| browser | productivity | Autonomous web browser |
|
||||
| trader | data | Crypto/stock trading assistant |
|
||||
| researcher | productivity | Deep research automation |
|
||||
| analytics | data | Data analysis and dashboards |
|
||||
| ... | | See each directory for details |
|
||||
|
||||
## Adding a New Hand
|
||||
|
||||
1. Create `hands/<name>/HAND.toml` (and optionally `SKILL.md`)
|
||||
2. Ensure `id` matches the directory name
|
||||
3. Run `python scripts/validate.py`
|
||||
4. Submit a PR
|
||||
|
||||
See [CONTRIBUTING.md](../CONTRIBUTING.md) for the full guide.
|
||||
@@ -0,0 +1,70 @@
|
||||
# Integrations
|
||||
|
||||
MCP (Model Context Protocol) server integration templates for LibreFang. Each integration connects LibreFang to an external service (GitHub, Slack, databases, etc.).
|
||||
|
||||
## Structure
|
||||
|
||||
```
|
||||
integrations/
|
||||
├── github.toml
|
||||
├── slack.toml
|
||||
├── postgresql.toml
|
||||
└── ...
|
||||
```
|
||||
|
||||
## Integration TOML Format
|
||||
|
||||
```toml
|
||||
id = "service-id" # Must match filename (without .toml)
|
||||
name = "Service Name"
|
||||
description = "What this integration provides"
|
||||
category = "devtools" # devtools | communication | storage | monitoring | data
|
||||
icon = "🐙"
|
||||
tags = ["relevant", "tags"]
|
||||
|
||||
[transport] # MCP server transport config
|
||||
type = "stdio" # "stdio" or "sse"
|
||||
command = "npx"
|
||||
args = ["-y", "@pkg/mcp-server"]
|
||||
|
||||
[[required_env]] # Required environment variables
|
||||
name = "SERVICE_API_KEY"
|
||||
label = "API Key"
|
||||
help = "How to obtain this key"
|
||||
is_secret = true
|
||||
get_url = "https://..."
|
||||
|
||||
[oauth] # Optional: OAuth config
|
||||
provider = "github"
|
||||
scopes = ["repo"]
|
||||
auth_url = "https://..."
|
||||
token_url = "https://..."
|
||||
|
||||
[health_check]
|
||||
interval_secs = 60
|
||||
unhealthy_threshold = 3
|
||||
|
||||
setup_instructions = """
|
||||
Step-by-step setup guide for users.
|
||||
"""
|
||||
```
|
||||
|
||||
## Current Integrations (25)
|
||||
|
||||
| Integration | Category | Service |
|
||||
|-------------|----------|---------|
|
||||
| github | devtools | GitHub repos, issues, PRs |
|
||||
| slack | communication | Slack messaging |
|
||||
| notion | productivity | Notion pages and databases |
|
||||
| postgresql | storage | PostgreSQL database |
|
||||
| ... | | See each file for details |
|
||||
|
||||
## Adding a New Integration
|
||||
|
||||
1. Create `integrations/<name>.toml`
|
||||
2. Ensure `id` matches the filename
|
||||
3. Test the MCP server command locally
|
||||
4. Run `python scripts/validate.py`
|
||||
5. Submit a PR
|
||||
|
||||
See [CONTRIBUTING.md](../CONTRIBUTING.md) for the full guide.
|
||||
@@ -0,0 +1,62 @@
|
||||
# Plugins
|
||||
|
||||
Plugin packages for LibreFang. Plugins extend agent behavior through lifecycle hooks -- they can inject memories, modify context, or perform side effects during conversations.
|
||||
|
||||
## Structure
|
||||
|
||||
```
|
||||
plugins/
|
||||
└── echo-memory/
|
||||
├── plugin.toml # Plugin manifest
|
||||
├── hooks/
|
||||
│ ├── ingest.py # Called on user message
|
||||
│ └── after_turn.py # Called after each turn
|
||||
└── requirements.txt # Python dependencies
|
||||
```
|
||||
|
||||
## plugin.toml Format
|
||||
|
||||
```toml
|
||||
name = "plugin-name" # Must match directory name
|
||||
version = "0.1.0"
|
||||
description = "What this plugin does"
|
||||
author = "author-name"
|
||||
|
||||
[hooks]
|
||||
ingest = "hooks/ingest.py" # Receives user message, can return memories
|
||||
after_turn = "hooks/after_turn.py" # Post-turn processing
|
||||
```
|
||||
|
||||
## Hook Protocol
|
||||
|
||||
Hooks communicate via stdin/stdout JSON:
|
||||
|
||||
### ingest hook
|
||||
|
||||
```
|
||||
stdin: {"type": "ingest", "agent_id": "...", "message": "user message"}
|
||||
stdout: {"type": "ingest_result", "memories": [{"content": "..."}]}
|
||||
```
|
||||
|
||||
### after_turn hook
|
||||
|
||||
```
|
||||
stdin: {"type": "after_turn", "agent_id": "...", "messages": [...]}
|
||||
stdout: {"type": "ok"}
|
||||
```
|
||||
|
||||
## Current Plugins (1)
|
||||
|
||||
| Plugin | Description |
|
||||
|--------|-------------|
|
||||
| echo-memory | Demo plugin that echoes user messages as recalled memories |
|
||||
|
||||
## Adding a New Plugin
|
||||
|
||||
1. Create `plugins/<name>/plugin.toml`
|
||||
2. Add hook scripts in `hooks/`
|
||||
3. List dependencies in `requirements.txt` (prefer stdlib-only)
|
||||
4. Run `python scripts/validate.py`
|
||||
5. Submit a PR
|
||||
|
||||
See [CONTRIBUTING.md](../CONTRIBUTING.md) for the full guide.
|
||||
@@ -0,0 +1,64 @@
|
||||
# Providers
|
||||
|
||||
LLM provider and model metadata for LibreFang. Each provider file defines the provider's API configuration and all available models with pricing, context windows, and capability flags.
|
||||
|
||||
## Structure
|
||||
|
||||
```
|
||||
providers/
|
||||
├── anthropic.toml
|
||||
├── openai.toml
|
||||
├── groq.toml
|
||||
└── ... (46 providers, 220+ models)
|
||||
```
|
||||
|
||||
## Provider TOML Format
|
||||
|
||||
```toml
|
||||
[provider]
|
||||
id = "provider-id" # Unique identifier (lowercase, hyphenated)
|
||||
display_name = "Provider Name"
|
||||
api_key_env = "PROVIDER_API_KEY" # Env var for API key
|
||||
base_url = "https://api.example.com"
|
||||
key_required = true
|
||||
|
||||
[[models]]
|
||||
id = "model-id" # Exact API model ID
|
||||
display_name = "Model Name"
|
||||
tier = "smart" # frontier | smart | balanced | fast | local
|
||||
context_window = 128000
|
||||
max_output_tokens = 16384
|
||||
input_cost_per_m = 2.50 # USD per million input tokens
|
||||
output_cost_per_m = 10.0 # USD per million output tokens
|
||||
supports_tools = true
|
||||
supports_vision = false
|
||||
supports_streaming = true
|
||||
aliases = ["short-name"]
|
||||
```
|
||||
|
||||
## Tier Definitions
|
||||
|
||||
| Tier | Description | Examples |
|
||||
|------|-------------|----------|
|
||||
| `frontier` | Most capable, cutting-edge | Claude Opus, GPT-4.1 |
|
||||
| `smart` | Smart, cost-effective | Claude Sonnet, Gemini 2.5 Flash |
|
||||
| `balanced` | Balanced speed/cost | GPT-4.1 Mini, Llama 3.3 70B |
|
||||
| `fast` | Fastest, cheapest | GPT-4o Mini, Claude Haiku |
|
||||
| `local` | Local models, zero cost | Ollama, vLLM, LM Studio |
|
||||
|
||||
## Validation
|
||||
|
||||
```bash
|
||||
python scripts/validate.py
|
||||
```
|
||||
|
||||
Checks: required fields, valid tiers, non-negative costs, no duplicate model IDs.
|
||||
|
||||
## Adding or Updating a Model
|
||||
|
||||
1. Edit or create the provider file in `providers/`
|
||||
2. Use exact API model IDs and verify pricing from official sources
|
||||
3. Run `python scripts/validate.py`
|
||||
4. Submit a PR
|
||||
|
||||
See [CONTRIBUTING.md](../CONTRIBUTING.md) for the full guide and pricing source links.
|
||||
@@ -0,0 +1,35 @@
|
||||
# Scripts
|
||||
|
||||
Utility scripts for maintaining the LibreFang registry.
|
||||
|
||||
## validate.py
|
||||
|
||||
Validates all TOML content files across the registry.
|
||||
|
||||
```bash
|
||||
python scripts/validate.py
|
||||
```
|
||||
|
||||
### What It Checks
|
||||
|
||||
**Per content type:**
|
||||
- **Providers** -- required fields, valid tiers, non-negative costs, no duplicate model IDs
|
||||
- **Agents** -- required fields (name, description, module), name matches directory
|
||||
- **Hands** -- required fields (id, name, description), valid category, [agent] section, id matches directory
|
||||
- **Integrations** -- required fields (id, name), [transport] section, id matches filename
|
||||
- **Skills** -- [skill] section with name, [runtime] with valid type
|
||||
- **Plugins** -- name matches directory, [hooks] section, hook files exist
|
||||
|
||||
**Cross-type checks:**
|
||||
- Routing alias collisions between agents and hands (reported as warnings)
|
||||
- Cross-file duplicate model IDs within the same provider
|
||||
|
||||
### Requirements
|
||||
|
||||
- Python 3.11+ (uses `tomllib`)
|
||||
- Or Python 3.8+ with `pip install tomli`
|
||||
|
||||
### Exit Codes
|
||||
|
||||
- `0` -- all checks passed
|
||||
- `1` -- one or more validation errors
|
||||
@@ -0,0 +1,80 @@
|
||||
# Skills
|
||||
|
||||
Reusable skill definitions for LibreFang agents. Skills are either prompt templates or code scripts that agents can invoke to perform specific tasks.
|
||||
|
||||
## Structure
|
||||
|
||||
```
|
||||
skills/
|
||||
├── custom-skill-prompt/
|
||||
│ └── skill.toml # Prompt-only skill
|
||||
└── custom-skill-python/
|
||||
├── skill.toml # Skill manifest
|
||||
└── main.py # Python implementation
|
||||
```
|
||||
|
||||
## Skill Types
|
||||
|
||||
### Prompt-Only
|
||||
|
||||
No code needed -- pure prompt engineering:
|
||||
|
||||
```toml
|
||||
[skill]
|
||||
name = "meeting-agenda"
|
||||
version = "0.1.0"
|
||||
description = "Generate a structured meeting agenda"
|
||||
tags = ["meeting", "productivity"]
|
||||
|
||||
[runtime]
|
||||
type = "promptonly"
|
||||
|
||||
[input]
|
||||
topic = { type = "string", description = "The meeting topic", required = true }
|
||||
duration_minutes = { type = "string", description = "Duration in minutes", required = true }
|
||||
|
||||
[prompt]
|
||||
template = """
|
||||
Create a meeting agenda for:
|
||||
Topic: {{topic}}
|
||||
Duration: {{duration_minutes}} minutes
|
||||
"""
|
||||
```
|
||||
|
||||
### Python
|
||||
|
||||
Custom logic with a Python entry point:
|
||||
|
||||
```toml
|
||||
[skill]
|
||||
name = "my-skill"
|
||||
version = "0.1.0"
|
||||
description = "Skill with custom logic"
|
||||
|
||||
[runtime]
|
||||
type = "python"
|
||||
entry = "main.py"
|
||||
|
||||
[input]
|
||||
data = { type = "string", description = "Input data", required = true }
|
||||
```
|
||||
|
||||
### Other Runtimes
|
||||
|
||||
Also supported: `node`, `shell`.
|
||||
|
||||
## Testing Skills Locally
|
||||
|
||||
```bash
|
||||
librefang skill test ./skills/custom-skill-prompt \
|
||||
--input '{"topic": "Q1 planning", "duration_minutes": "30"}'
|
||||
```
|
||||
|
||||
## Adding a New Skill
|
||||
|
||||
1. Create `skills/<name>/skill.toml`
|
||||
2. Add implementation files if not `promptonly`
|
||||
3. Run `python scripts/validate.py`
|
||||
4. Submit a PR
|
||||
|
||||
See [CONTRIBUTING.md](../CONTRIBUTING.md) for the full guide.
|
||||
Reference in new issue
Block a user