A production-grade capability package for portable, composable, reusable agent actions.
Built from scratch by WorthDoing AI — not a wrapper, not a toy, not another agent toolkit clone.
WorthDoing Capabilities is a structured, production-grade Python package for building portable, composable, and reusable agent capabilities. It is not a utility library. It is not an API wrapper. It is not another agent toolkit that stitches together a dozen third-party SDKs behind a thin facade.
Every capability in this package is defined by a declarative YAML contract that specifies its inputs, outputs, authentication requirements, caching behavior, and planner hints. A runtime engine discovers, validates, and executes capabilities through a unified interface. A registry indexes them. Executors handle the actual work — whether that means calling a REST API, running a Python function, executing a shell command, or chaining multiple capabilities into a workflow.
The result is a system where capabilities are first-class citizens: inspectable, testable, cacheable, and auditable — individually and as part of larger agent pipelines.
| Problem | Solution |
|---|---|
| Agent toolkits are collections of loose wrappers with no unifying architecture | Structured capability architecture with contracts, registry, and runtime engine |
| No standard for describing what a capability does, what it needs, and what it returns | Declarative YAML contracts with input/output schemas, auth requirements, cache policies, and planner hints |
| Auth scattered across implementations — every tool handles credentials differently | Centralized auth resolver that resolves credentials once and injects them uniformly |
| No caching strategy — every call hits the network regardless of determinism | Built-in deterministic caching per capability with configurable TTL and key strategies |
| Hard to test individual capabilities in isolation | Per-capability test structure with dedicated fixtures and mock support |
| No execution audit trail — impossible to debug what happened after the fact | Standardized execution records for every run with inputs, outputs, timing, and status |
The system is organized into five distinct layers, each with a clear responsibility boundary:
+-------------------------------------------------------------------+
| CLI Interface (Typer) |
| wdcap list | inspect | run | validate | history |
+-------------------------------------------------------------------+
| Python API (CapabilityRuntime) |
| list_capabilities | inspect | run | validate | get_history |
+-------------------------------------------------------------------+
| Runtime Engine Layer |
| Discovery | Contract Loading | Validation | Execution Dispatch |
+-------------------------------------------------------------------+
| Executor Layer |
| HTTP Executor | Python Executor | Shell Executor | Workflow Exec |
+-------------------------------------------------------------------+
| Foundation Services |
| Validation | Auth Resolver | Cache Store | Memory / Records |
+-------------------------------------------------------------------+
| Layer | Role |
|---|---|
| CLI Interface | Human-facing commands powered by Typer and Rich. Thin wrapper over the Python API. |
| Python API | The primary programmatic interface. Instantiate CapabilityRuntime, call methods. |
| Runtime Engine | Discovers capabilities from the filesystem, loads and validates contracts, dispatches execution to the correct executor. |
| Executor Layer | Four specialized executors that know how to perform the actual work for each capability type. |
| Foundation Services | Cross-cutting concerns: input/output validation (Pydantic v2), credential resolution, deterministic caching, and execution record keeping. |
WorthDoing Capabilities ships with 7 production-ready capabilities across 5 categories:
| Capability | Category | Executor | Description | Auth | Cache |
|---|---|---|---|---|---|
web_search |
Search | HTTP | Search the web via a configurable search API and return structured results | API Key | 5 min TTL |
url_fetch |
Data Retrieval | HTTP | Fetch and extract content from a URL — raw HTML, text, or parsed metadata | None | 10 min TTL |
market_data.quote |
Finance | HTTP | Retrieve real-time stock/crypto quotes with price, volume, and change data | API Key | 1 min TTL |
shell.run |
System | Shell | Execute a local shell command with sanitization, timeout, and output capture | None | No cache |
file.read |
System | Python | Read local file contents with encoding detection and size limits | None | No cache |
embeddings.generate |
AI / ML | HTTP | Generate vector embeddings for text via a configurable embeddings API | API Key | 30 min TTL |
workflow.simple_chain |
Orchestration | Workflow | Chain multiple capabilities sequentially, piping outputs into inputs | Inherited | No cache |
Each capability lives in its own directory under src/worthdoing_capabilities/capabilities/ with a YAML contract, executor implementation, and dedicated test directory.
Every capability is defined by a declarative YAML contract. The contract is the single source of truth for what a capability does, what it needs, what it returns, how it authenticates, how it caches, and how a planner should reason about it.
capability:
name: market_data.quote
version: "1.0.0"
description: "Retrieve real-time stock or crypto quote data"
category: finance
executor: http
input:
schema:
type: object
properties:
symbol:
type: string
description: "Ticker symbol (e.g., AAPL, BTC-USD)"
interval:
type: string
enum: ["1d", "5d", "1mo"]
default: "1d"
required:
- symbol
output:
schema:
type: object
properties:
symbol:
type: string
price:
type: number
change:
type: number
change_percent:
type: number
volume:
type: integer
timestamp:
type: string
format: datetime
auth:
method: api_key
env_var: MARKET_DATA_API_KEY
header: X-API-Key
cache:
enabled: true
ttl_seconds: 60
key_fields:
- symbol
- interval
planner:
use_when: "User asks for stock price, crypto price, market quote, or ticker data"
cost: low
latency: low
deterministic: false| Group | Purpose |
|---|---|
| capability | Identity — name, version, description, category, and which executor to use |
| input | JSON Schema defining the expected input, including required fields and defaults |
| output | JSON Schema defining the guaranteed output structure |
| auth | Authentication method, environment variable name, and how to inject credentials |
| cache | Whether caching is enabled, TTL, and which input fields form the cache key |
| planner | Hints for AI planners — when to use this capability, expected cost, latency, and determinism |
Executors are the runtime components that know how to actually perform the work described by a capability contract. The runtime engine dispatches to the correct executor based on the executor field in the contract.
| Executor | Type | Description | Use Cases |
|---|---|---|---|
| HTTP | http |
Makes REST API calls using httpx. Supports GET/POST, headers, query params, JSON bodies, and async execution. Auth credentials are injected automatically. | web_search, url_fetch, market_data.quote, embeddings.generate |
| Python | python |
Calls internal Python functions directly. The function path is specified in the contract. Runs in-process with full access to the Python environment. | file.read, custom internal logic |
| Shell | shell |
Executes local shell commands with input sanitization, configurable timeouts, and stdout/stderr capture. Commands are validated against an allowlist. | shell.run, local tooling |
| Workflow | workflow |
Chains multiple capabilities sequentially. Each step's output can be mapped into the next step's input. Execution records are created for the workflow and each sub-step. | workflow.simple_chain, multi-step pipelines |
All executors implement a common interface:
class BaseExecutor:
async def execute(
self,
contract: CapabilityContract,
inputs: dict,
auth: AuthContext | None,
cache: CacheStore,
) -> ExecutionResult:
...The primary interface for using WorthDoing Capabilities programmatically:
from worthdoing_capabilities import CapabilityRuntime
# Initialize the runtime — discovers and loads all capability contracts
runtime = CapabilityRuntime()
# List all registered capabilities
capabilities = runtime.list_capabilities()
for cap in capabilities:
print(f"{cap.name} ({cap.category}) — {cap.description}")
# Inspect a specific capability's full contract
contract = runtime.inspect("market_data.quote")
print(contract.input.schema)
print(contract.auth.method)
print(contract.cache.ttl_seconds)
# Run a capability
result = runtime.run("market_data.quote", {"symbol": "AAPL"})
print(result.output) # {"symbol": "AAPL", "price": 198.50, ...}
print(result.cached) # False (first call)
print(result.duration_ms) # 230
# Run again — hits cache
result2 = runtime.run("market_data.quote", {"symbol": "AAPL"})
print(result2.cached) # True
# Validate a contract file
issues = runtime.validate("capabilities/market_data/capability.yaml")
print(issues) # [] (no issues)
# Get execution history
history = runtime.get_history()
for record in history:
print(f"{record.capability} — {record.status} — {record.duration_ms}ms")All executors support async execution via httpx:
import asyncio
from worthdoing_capabilities import CapabilityRuntime
async def main():
runtime = CapabilityRuntime()
result = await runtime.run_async("web_search", {"query": "WorthDoing AI"})
print(result.output)
asyncio.run(main())WorthDoing Capabilities includes a full command-line interface powered by Typer and Rich:
wdcap list Capability Category Executor Cache Auth
───────────────────────────────────────────────────────────────────
web_search search http 5m TTL api_key
url_fetch data http 10m TTL none
market_data.quote finance http 1m TTL api_key
shell.run system shell none none
file.read system python none none
embeddings.generate ai http 30m TTL api_key
workflow.simple_chain orchestration workflow none inherited
wdcap inspect market_data.quote market_data.quote v1.0.0
──────────────────────────
Description: Retrieve real-time stock or crypto quote data
Category: finance
Executor: http
Auth: api_key (MARKET_DATA_API_KEY)
Cache: 60s TTL on [symbol, interval]
Input Schema:
symbol string required Ticker symbol (e.g., AAPL, BTC-USD)
interval string optional 1d | 5d | 1mo (default: 1d)
Output Schema:
symbol string
price number
change number
change_percent number
volume integer
timestamp datetime
wdcap run market_data.quote --input '{"symbol": "AAPL"}'{
"symbol": "AAPL",
"price": 198.50,
"change": 2.35,
"change_percent": 1.20,
"volume": 54200000,
"timestamp": "2026-04-13T16:00:00Z"
}wdcap validate capabilities/market_data/capability.yaml Validating capabilities/market_data/capability.yaml...
[PASS] Contract structure valid
[PASS] Input schema valid
[PASS] Output schema valid
[PASS] Auth configuration valid
[PASS] Cache configuration valid
[PASS] Planner hints present
All checks passed.
wdcap history Timestamp Capability Status Duration Cached
──────────────────────────────────────────────────────────────────────
2026-04-13 14:32:01 market_data.quote success 230ms no
2026-04-13 14:32:05 market_data.quote success 2ms yes
2026-04-13 14:33:12 web_search success 890ms no
2026-04-13 14:35:44 shell.run success 45ms no
worthdoing-capabilities/
├── pyproject.toml # Package config, deps, CLI entry point
├── README.md # This file
├── LICENSE # MIT License
├── .gitignore # Python ignores
├── docs/ # Documentation
├── examples/ # Usage examples
├── scripts/ # Dev & build scripts
├── src/
│ └── worthdoing_capabilities/
│ ├── __init__.py # Public API exports
│ ├── cli/
│ │ └── main.py # Typer CLI application
│ ├── contracts/
│ │ ├── __init__.py
│ │ ├── models.py # Pydantic models for contracts
│ │ └── loader.py # YAML contract loader
│ ├── registry/
│ │ └── __init__.py # Capability discovery & indexing
│ ├── runtime/
│ │ └── __init__.py # Runtime engine (orchestrator)
│ ├── executors/
│ │ └── __init__.py # HTTP, Python, Shell, Workflow executors
│ ├── validation/
│ │ ├── __init__.py
│ │ └── validator.py # Input/output validation (Pydantic v2)
│ ├── auth/
│ │ ├── __init__.py
│ │ └── resolver.py # Centralized auth credential resolver
│ ├── cache/
│ │ ├── __init__.py
│ │ └── store.py # Deterministic cache store
│ ├── memory/
│ │ ├── __init__.py
│ │ └── record.py # Execution record model
│ └── capabilities/ # Built-in capabilities
│ ├── web_search/
│ │ ├── capability.yaml # Contract
│ │ ├── executor.py # Implementation
│ │ └── tests/ # Capability-specific tests
│ ├── url_fetch/
│ │ ├── capability.yaml
│ │ ├── executor.py
│ │ └── tests/
│ ├── market_data/
│ │ ├── capability.yaml
│ │ ├── executor.py
│ │ └── tests/
│ ├── shell/
│ │ ├── capability.yaml
│ │ ├── executor.py
│ │ └── tests/
│ ├── file_read/
│ │ ├── capability.yaml
│ │ ├── executor.py
│ │ └── tests/
│ ├── embeddings/
│ │ ├── capability.yaml
│ │ ├── executor.py
│ │ └── tests/
│ └── workflow/
│ ├── capability.yaml
│ ├── executor.py
│ └── tests/
└── tests/
├── fixtures/ # Shared test fixtures
├── unit/ # Unit tests
└── integration/ # Integration tests
# Clone the repository
git clone https://github.com/Worth-Doing/worthdoing-capabilities.git
cd worthdoing-capabilities
# Install in editable mode with dev dependencies
pip install -e ".[dev]"
# Verify installation
wdcap list- Python 3.11+ (3.12 and 3.13 also supported)
- pip 23+
| Package | Version | Purpose |
|---|---|---|
| pydantic | >=2.0 | Contract models, input/output validation |
| httpx | >=0.27 | Async HTTP client for API-based capabilities |
| typer | >=0.12 | CLI framework |
| pyyaml | >=6.0 | YAML contract parsing |
| rich | >=13.0 | Terminal formatting and tables |
pytestpytest --cov=worthdoing_capabilities --cov-report=term-missing# Unit tests only
pytest tests/unit/
# Integration tests only
pytest tests/integration/
# Tests for a specific capability
pytest src/worthdoing_capabilities/capabilities/market_data/tests/
# Run with verbose output
pytest -v| Directory | Purpose |
|---|---|
tests/unit/ |
Unit tests for contracts, registry, runtime, executors, validation, auth, cache, memory |
tests/integration/ |
End-to-end tests that exercise the full runtime pipeline |
tests/fixtures/ |
Shared test data — sample contracts, mock responses, fixture configs |
capabilities/*/tests/ |
Per-capability tests co-located with their implementations |
| # | Principle | Description |
|---|---|---|
| 1 | Capability-First | Capabilities are the primary abstraction. Everything else exists to serve them. The system is not organized around tools, functions, or endpoints — it is organized around capabilities with contracts. |
| 2 | Runtime Separation | The contract (what a capability does) is strictly separated from the runtime (how it gets executed). You can inspect, validate, and reason about capabilities without executing them. |
| 3 | Declarative Contracts | YAML contracts are the single source of truth. No magic decorators, no implicit registration, no convention-over-configuration guessing. If it is not in the contract, it does not exist. |
| 4 | Small Focused Modules | Every module has one job. The auth resolver resolves auth. The cache store caches. The validator validates. No god objects, no kitchen-sink utilities. |
| 5 | Future Extensibility | The executor interface, contract format, and registry are all designed to be extended without modifying existing code. New executors, new capabilities, new auth methods — all additive. |
| 6 | Strong Validation | Inputs and outputs are validated against their schemas on every execution. Bad data fails fast with clear error messages, not silently deep in a third-party API call. |
| 7 | Reusability | Capabilities are portable. A capability built here can be used by any agent, any pipeline, any orchestrator that speaks the contract format. No vendor lock-in, no framework coupling. |
- PyPI publication —
pip install worthdoing-capabilities - Additional capabilities:
llm.complete,code.execute,pdf.extract,calendar.events - Enhanced CLI with
wdcap initscaffolding for new capabilities - OpenAPI-to-contract generator — auto-generate contracts from OpenAPI specs
- Comprehensive documentation site
- External capability packages — install third-party capabilities via pip
- Remote registries — discover and pull capabilities from hosted registries
- Capability versioning and migration support
- Webhook executor — trigger and wait for external webhooks
- Rate limiting and circuit breaker per capability
- Capability marketplace — publish, discover, and install community capabilities
- Signed contracts — cryptographic verification of capability provenance
- Planner integration — native integration with WorthDoing AI agent planner
- Distributed execution — run capabilities across multiple nodes
- Real-time capability monitoring dashboard
Contributions are welcome. This is a serious infrastructure project and there is a lot to build.
- New capability implementations (especially data retrieval, AI/ML, and productivity categories)
- Executor improvements (retry logic, connection pooling, streaming support)
- Contract format enhancements
- Test coverage expansion
- Documentation and usage examples
- Fork the repository
- Create your feature branch (
git checkout -b feature/new-capability) - Write tests for your changes
- Ensure all tests pass (
pytest) - Ensure code quality (
ruff check . && mypy src/) - Commit your changes (
git commit -m 'Add new capability') - Push to the branch (
git push origin feature/new-capability) - Open a Pull Request
This project is licensed under the MIT License. See the LICENSE file for details.
Built with purpose by WorthDoing AI
AI That Decides What Matters
