docs: rewrite README and CONTRIBUTING for full registry scope
- README now covers all 5 content types (agents, hands, integrations, skills, providers) - CONTRIBUTING has per-type instructions and checklists - validate.py expanded to validate agents, hands, integrations, and skills - PR template covers all content types - Added new-content.yml issue template for non-model contributions - CI workflow updated to Python 3.12
This commit is contained in:
Evan Hu committed
1 parent
17d32ed4a7
commit
1f3ef406ee
6 files changed
+639
-268
No files matched your search
+187
-59
@@ -1,59 +1,202 @@
|
||||
# Contributing to LibreFang Model Catalog
|
||||
# Contributing to LibreFang Registry
|
||||
|
||||
Thank you for helping keep the model catalog up to date! This guide explains how to add or update model entries.
|
||||
Thank you for helping grow the LibreFang ecosystem! This guide explains how to add or update content for each type.
|
||||
|
||||
## How to Add a New Model
|
||||
## General Workflow
|
||||
|
||||
### 1. Fork & Clone
|
||||
1. Fork & clone the repository
|
||||
2. Create a branch: `git checkout -b feat/add-my-content`
|
||||
3. Add or edit files in the appropriate directory
|
||||
4. Run validation: `python scripts/validate.py`
|
||||
5. Submit a Pull Request
|
||||
|
||||
```bash
|
||||
git clone https://github.com/<your-fork>/model-catalog.git
|
||||
cd model-catalog
|
||||
```
|
||||
## Adding an Agent
|
||||
|
||||
### 2. Find the Right Provider File
|
||||
|
||||
Each provider has its own file in `providers/`. For example:
|
||||
- OpenAI models go in `providers/openai.toml`
|
||||
- Anthropic models go in `providers/anthropic.toml`
|
||||
|
||||
If the provider doesn't exist yet, create a new file (e.g. `providers/newprovider.toml`) with the `[provider]` section and your `[[models]]` entries.
|
||||
|
||||
### 3. Add Your Model Entry
|
||||
|
||||
Append a `[[models]]` block to the provider file:
|
||||
Create a directory `agents/<name>/` with an `agent.toml` file:
|
||||
|
||||
```toml
|
||||
name = "my-agent"
|
||||
version = "0.1.0"
|
||||
description = "What this agent does"
|
||||
author = "your-name"
|
||||
module = "builtin:chat"
|
||||
|
||||
[model]
|
||||
provider = "default"
|
||||
model = "default"
|
||||
max_tokens = 4096
|
||||
temperature = 0.7
|
||||
system_prompt = """Your system prompt here."""
|
||||
|
||||
[capabilities]
|
||||
tools = ["web_search", "file_read"]
|
||||
```
|
||||
|
||||
### Agent Checklist
|
||||
|
||||
- [ ] `name` matches the directory name
|
||||
- [ ] `description` is clear and concise (one sentence)
|
||||
- [ ] `system_prompt` provides clear behavioral instructions
|
||||
- [ ] `tools` only lists tools the agent actually needs
|
||||
- [ ] Routing aliases (if any) are relevant and don't conflict with existing agents
|
||||
|
||||
## Adding a Hand
|
||||
|
||||
Create a directory `hands/<name>/` with a `HAND.toml` file and optionally a `SKILL.md`:
|
||||
|
||||
```toml
|
||||
id = "my-hand"
|
||||
name = "My Hand"
|
||||
description = "What this hand does"
|
||||
category = "productivity" # communication | content | data | development | devops | finance | productivity | research | social
|
||||
icon = "🔧"
|
||||
|
||||
tools = ["tool1", "tool2"]
|
||||
|
||||
[routing]
|
||||
aliases = ["activate my hand", "do the thing"]
|
||||
|
||||
[agent]
|
||||
name = "my-hand-agent"
|
||||
module = "builtin:chat"
|
||||
system_prompt = """Your agent prompt here."""
|
||||
|
||||
[[settings]]
|
||||
key = "some_setting"
|
||||
label = "Setting Label"
|
||||
setting_type = "toggle"
|
||||
default = "true"
|
||||
```
|
||||
|
||||
### Hand Checklist
|
||||
|
||||
- [ ] `id` matches the directory name
|
||||
- [ ] `category` is valid (`communication`, `content`, `data`, `development`, `devops`, `finance`, `productivity`, `research`, `social`)
|
||||
- [ ] `tools` lists all required tools
|
||||
- [ ] `[agent]` section has a complete system prompt
|
||||
- [ ] `[[requires]]` sections list any external dependencies (binaries, services)
|
||||
- [ ] `[[settings]]` sections provide user-configurable options where appropriate
|
||||
|
||||
## Adding an Integration
|
||||
|
||||
Create a file `integrations/<name>.toml`:
|
||||
|
||||
```toml
|
||||
id = "my-service"
|
||||
name = "My Service"
|
||||
description = "What this integration provides"
|
||||
category = "devtools" # devtools | communication | storage | monitoring | data
|
||||
icon = "🔌"
|
||||
tags = ["relevant", "tags"]
|
||||
|
||||
[transport]
|
||||
type = "stdio"
|
||||
command = "npx"
|
||||
args = ["-y", "@some/mcp-server"]
|
||||
|
||||
[[required_env]]
|
||||
name = "MY_SERVICE_API_KEY"
|
||||
label = "API Key"
|
||||
help = "Get your key from https://..."
|
||||
is_secret = true
|
||||
get_url = "https://my-service.com/settings/api-keys"
|
||||
|
||||
setup_instructions = """
|
||||
1. Get an API key from ...
|
||||
2. Paste it into the field above.
|
||||
"""
|
||||
```
|
||||
|
||||
### Integration Checklist
|
||||
|
||||
- [ ] `id` matches the filename (without `.toml`)
|
||||
- [ ] `[transport]` section is correct (test the MCP server command locally)
|
||||
- [ ] `[[required_env]]` lists all needed environment variables
|
||||
- [ ] `setup_instructions` are clear enough for first-time users
|
||||
- [ ] `is_secret = true` for any sensitive values (API keys, tokens)
|
||||
|
||||
## Adding a Skill
|
||||
|
||||
Create a directory `skills/<name>/` with a `skill.toml` and optionally implementation files:
|
||||
|
||||
### Prompt-only Skill
|
||||
|
||||
```toml
|
||||
[skill]
|
||||
name = "my-skill"
|
||||
version = "0.1.0"
|
||||
description = "What this skill does"
|
||||
author = "your-name"
|
||||
tags = ["relevant", "tags"]
|
||||
|
||||
[runtime]
|
||||
type = "promptonly"
|
||||
|
||||
[input]
|
||||
param1 = { type = "string", description = "Description", required = true }
|
||||
|
||||
[prompt]
|
||||
template = """Your prompt template using {{param1}}."""
|
||||
```
|
||||
|
||||
### Python Skill
|
||||
|
||||
```toml
|
||||
[skill]
|
||||
name = "my-skill"
|
||||
version = "0.1.0"
|
||||
description = "What this skill does"
|
||||
|
||||
[runtime]
|
||||
type = "python"
|
||||
entry = "main.py"
|
||||
```
|
||||
|
||||
Plus a `main.py` with your implementation.
|
||||
|
||||
### Skill Checklist
|
||||
|
||||
- [ ] `name` matches the directory name
|
||||
- [ ] `[runtime].type` is `promptonly` or `python`
|
||||
- [ ] `[input]` section documents all parameters
|
||||
- [ ] Prompt-only skills have a `[prompt].template` with correct `{{param}}` placeholders
|
||||
- [ ] Python skills include all required files
|
||||
|
||||
## Adding or Updating a Provider / Model
|
||||
|
||||
Edit the appropriate provider file in `providers/`. If the provider doesn't exist, create a new file.
|
||||
|
||||
```toml
|
||||
[provider]
|
||||
id = "my-provider"
|
||||
display_name = "My Provider"
|
||||
api_key_env = "MY_PROVIDER_API_KEY"
|
||||
base_url = "https://api.my-provider.com"
|
||||
key_required = true
|
||||
|
||||
[[models]]
|
||||
id = "new-model-id" # The exact API model ID
|
||||
display_name = "New Model Name" # Human-readable name
|
||||
tier = "smart" # frontier | smart | balanced | fast | local
|
||||
id = "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
|
||||
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 = [] # Optional short names
|
||||
aliases = ["short-name"]
|
||||
```
|
||||
|
||||
### 4. Validate
|
||||
### Provider Checklist
|
||||
|
||||
```bash
|
||||
python scripts/validate.py
|
||||
```
|
||||
|
||||
This checks:
|
||||
- All TOML files parse correctly
|
||||
- Required fields are present
|
||||
- Tier values are valid
|
||||
- Costs are non-negative
|
||||
- No duplicate model IDs
|
||||
|
||||
### 5. Submit a Pull Request
|
||||
|
||||
Push your branch and open a PR. The PR template will guide you through the checklist.
|
||||
- [ ] `python scripts/validate.py` passes
|
||||
- [ ] No duplicate model IDs
|
||||
- [ ] Pricing is in USD per million tokens
|
||||
- [ ] Tier is one of: `frontier`, `smart`, `balanced`, `fast`, `local`
|
||||
- [ ] `context_window` and `max_output_tokens` are positive integers
|
||||
- [ ] Boolean capability fields are correct
|
||||
- [ ] Pricing verified from official source
|
||||
|
||||
## Where to Find Model Information
|
||||
|
||||
@@ -64,26 +207,11 @@ Push your branch and open a PR. The PR template will guide you through the check
|
||||
- **Mistral**: https://mistral.ai/technology/#pricing
|
||||
- **Groq**: https://wow.groq.com/
|
||||
- **xAI**: https://docs.x.ai/docs
|
||||
- **Cohere**: https://cohere.com/pricing
|
||||
- **Together**: https://www.together.ai/pricing
|
||||
- **Fireworks**: https://fireworks.ai/pricing
|
||||
- **Perplexity**: https://docs.perplexity.ai/guides/pricing
|
||||
|
||||
## Tier Definitions
|
||||
|
||||
| Tier | Description | Examples |
|
||||
|------|-------------|----------|
|
||||
| `frontier` | Most capable, cutting-edge | Claude Opus, GPT-4.1, Gemini 2.5 Pro |
|
||||
| `smart` | Smart and cost-effective | Claude Sonnet, GPT-4o, Gemini 2.5 Flash |
|
||||
| `balanced` | Balanced speed and cost | GPT-4.1 Mini, Llama 3.3 70B |
|
||||
| `fast` | Fastest, cheapest | GPT-4o Mini, Claude Haiku, Gemma 2 9B |
|
||||
| `local` | Local models, zero cost | Ollama, vLLM, LM Studio |
|
||||
|
||||
## Guidelines
|
||||
|
||||
- **Pricing must be in USD per million tokens** -- convert from other units if needed
|
||||
- **Use the exact model ID** that the provider's API expects
|
||||
- **Don't guess** -- only add data you can verify from official sources
|
||||
- **One provider per file** -- don't mix providers in a single TOML file
|
||||
- **Keep aliases short** -- 1-3 word abbreviations that users would naturally type
|
||||
|
||||
- **Keep descriptions concise** -- one sentence that explains the purpose
|
||||
- **Test locally** -- try your content with LibreFang before submitting
|
||||
- **One PR per content type** -- don't mix agent additions with provider updates
|
||||
- **Keep aliases short** -- 1-3 word abbreviations users would naturally type
|
||||
Reference in new issue
Block a user