API Reference

Complete API documentation for claude-force Python package.

Core Components

Orchestration

AgentOrchestrator - Main orchestration engine for running agents and workflows
HybridOrchestrator - Intelligent model selection and cost optimization
WorkflowComposer - Create and manage custom multi-agent workflows

Agent Selection

SemanticAgentSelector - AI-powered agent recommendation using embeddings
AgentRouter - Agent routing and matching logic

Performance & Analytics

PerformanceTracker - Track execution metrics, costs, and performance
Analytics - Advanced analytics and reporting

Marketplace & Skills

AgentMarketplace - Install and share community agents
SkillsManager - Manage agent skills and capabilities
TemplateGallery - Project templates and scaffolding

Command-Line Interface

CLI Commands - All command-line interface commands and options

Utilities

ImportExport - Configuration import/export utilities
QuickStart - Project initialization and setup
Contribution - Contribution workflow helpers

Quick API Examples

Basic Agent Execution

from claude_force.orchestrator import AgentOrchestrator

orchestrator = AgentOrchestrator(
    config_path=".claude/claude.json",
    enable_tracking=True
)

result = orchestrator.run_agent(
    agent_name="code-reviewer",
    task="Review authentication module"
)

print(f"Success: {result.success}")
print(f"Output: {result.output}")

Semantic Agent Recommendation

from claude_force.semantic_selector import SemanticAgentSelector

selector = SemanticAgentSelector(config_path=".claude/claude.json")

matches = selector.match_agents(
    task_description="Find and fix security vulnerabilities",
    top_k=3
)

for match in matches:
    print(f"{match.agent_name}: {match.confidence:.2f}")

Hybrid Model Selection

from claude_force.hybrid_orchestrator import HybridOrchestrator

hybrid = HybridOrchestrator(
    auto_select_model=True,
    cost_threshold=0.50
)

# Automatically selects Haiku for simple tasks
result = hybrid.run_agent(
    "code-reviewer",
    "Fix typo in README"
)

# Automatically selects Sonnet/Opus for complex tasks
result = hybrid.run_agent(
    "backend-architect",
    "Design microservices architecture"
)

Performance Tracking

from claude_force.performance_tracker import PerformanceTracker

tracker = PerformanceTracker(metrics_dir=".claude/metrics")

# Record execution
tracker.record_execution(
    agent_name="code-reviewer",
    task="Review code",
    success=True,
    execution_time_ms=1500.0,
    model="claude-3-5-sonnet-20241022",
    input_tokens=150,
    output_tokens=250
)

# Get analytics
analytics = tracker.get_summary()
print(f"Total executions: {analytics['total_executions']}")
print(f"Total cost: ${analytics['total_cost']:.4f}")
print(f"Success rate: {analytics['success_rate']:.1%}")

Workflow Composition

from claude_force.workflow_composer import WorkflowComposer

composer = WorkflowComposer()

workflow = composer.compose(
    goal="Implement user authentication with security review and testing",
    include_marketplace=True
)

print(f"Workflow: {workflow.name}")
print(f"Steps: {len(workflow.steps)}")
print(f"Estimated cost: ${workflow.total_estimated_cost:.2f}")

for step in workflow.steps:
    print(f"  {step.step_number}. {step.agent.agent_name}: {step.description}")

Marketplace Operations

from claude_force.marketplace import AgentMarketplace

marketplace = AgentMarketplace()

# List available agents
agents = marketplace.list_agents(category="security")

# Search
results = marketplace.search("authentication security")

# Install agent
marketplace.install_agent(
    agent_name="oauth-specialist",
    target_dir=".claude"
)

API Conventions

Error Handling

All claude-force APIs use exception-based error handling:

from claude_force.orchestrator import AgentOrchestrator
from claude_force.exceptions import (
    AgentNotFoundError,
    APIKeyMissingError,
    ConfigurationError
)

try:
    orchestrator = AgentOrchestrator(config_path=".claude/claude.json")
    result = orchestrator.run_agent("code-reviewer", "Review code")
except APIKeyMissingError:
    print("Set ANTHROPIC_API_KEY environment variable")
except AgentNotFoundError as e:
    print(f"Agent not found: {e}")
except ConfigurationError as e:
    print(f"Invalid configuration: {e}")

Return Types

Most methods return typed objects:

AgentResult - Result of agent execution
AgentMatch - Agent recommendation with confidence
ExecutionMetrics - Performance metrics
ComposedWorkflow - Workflow composition
MarketplaceAgent - Marketplace agent information

Async Support

Currently, claude-force is synchronous. Async support is planned for v3.0.

Module Index

claude_force.orchestrator - Core orchestration
claude_force.semantic_selector - Semantic agent selection
claude_force.hybrid_orchestrator - Model selection
claude_force.performance_tracker - Performance tracking
claude_force.workflow_composer - Workflow composition
claude_force.marketplace - Agent marketplace
claude_force.skills_manager - Skills management
claude_force.analytics - Analytics and reporting
claude_force.agent_router - Agent routing
claude_force.template_gallery - Project templates
claude_force.import_export - Import/export utilities
claude_force.quick_start - Project initialization
claude_force.cli - Command-line interface

Type Annotations

All claude-force APIs use type hints:

from typing import List, Optional, Dict, Any
from claude_force.orchestrator import AgentResult

def run_agent(
    agent_name: str,
    task: str,
    model: Optional[str] = None
) -> AgentResult:
    """Run an agent with type-safe parameters"""
    pass

Configuration

Most APIs accept a config_path parameter pointing to claude.json:

orchestrator = AgentOrchestrator(config_path=".claude/claude.json")
selector = SemanticAgentSelector(config_path=".claude/claude.json")

Next Steps

Explore detailed documentation for each component
Check out Guides for tutorials
See Examples for real-world usage

Need help? Open an issue on GitHub.