API Reference

Home | Installation and Setup | Development Guidelines | AI Agent Integration Guide

This API reference provides detailed documentation of the AICollaborator framework's components, protocols, and interfaces. The documentation is structured to be useful for both human developers and AI agents.

Table of Contents

1. Core Components
2. Main Interfaces
   • AICollaborator
   • AITask
   • AIAgent
   • AIContext
3. Key Protocols
   • AICollaboratorAgent
   • TaskExecutable
   • ContextAware
   • HumanInteractive
4. Code Examples
5. AI-Readable Documentation

Core Components

The AICollaborator framework consists of the following core components:

Component	Purpose	Key Methods
AICollaborator	Main entry point	connect(), register(), execute()
AITask	Task representation	parseFromInput(), validate()
AIAgent	Agent protocol	processTask(), provideCapabilities()
AIContext	Context management	store(), retrieve(), update()

Main Interfaces

AICollaborator

The AICollaborator class serves as the main entry point for the framework, providing methods to connect AI agents, register them, and execute tasks.

Key Methods

// Initialize the collaborator instance
func init(configuration: CollaboratorConfig = .default) -> AICollaborator

// Connect an AI agent with credentials
func connect(agentType: AIAgentType, credentials: AICredentials) -> Bool

// Register an agent with the collaborator
func register(agent: AICollaboratorAgent) -> UUID

// Execute a task using available agents
func execute(task: AITask) -> AITaskResult

// Retrieve context for a specific session
func getContext(sessionId: UUID) -> AIContext?

AITask

The AITask protocol represents tasks that can be executed by AI agents, including methods for parsing input, validation, and result handling.

Key Properties and Methods

// Task identifier
var id: UUID { get }

// Task type (e.g., code generation, analysis)
var type: AITaskType { get }

// Task priority
var priority: TaskPriority { get }

// Parse task from input string
static func parseFromInput(_ input: String) -> AITask?

// Validate task parameters
func validate() -> Bool

// Check if task matches agent capabilities
func matchesCapabilities(_ capabilities: [AICapability]) -> Bool

AIAgent

The AIAgent protocol defines the interface for AI agents, including methods for processing tasks and providing capabilities.

// Agent identifier
var id: UUID { get }

// Agent type (e.g., LLM, rule-based)
var type: AIAgentType { get }

// Agent name
var name: String { get }

// Process a task and return a result
func processTask(_ task: AITask) -> AITaskResult

// Provide list of agent capabilities
func provideCapabilities() -> [AICapability]

// Check if agent can handle a specific task
func canHandle(task: AITask) -> Bool

AIContext

The AIContext class manages contextual information for AI agent interactions, including conversation history and task results.

// Store a value in the context
func store(key: String, value: Any) -> Bool

// Retrieve a value from the context
func retrieve(key: String) -> Any?

// Update an existing value
func update(key: String, value: Any) -> Bool

// Clear context or specific values
func clear(keys: [String]? = nil) -> Bool

// Get conversation history
func getConversationHistory() -> [AIMessage]

Key Protocols

AICollaboratorAgent

The AICollaboratorAgent protocol defines the interface for AI agents to integrate with the collaborator framework.

protocol AICollaboratorAgent {
    // Process a task and return a result
    func processTask(_ task: AITask) -> AITaskResult
    
    // Provide list of agent capabilities
    func provideCapabilities() -> [AICapability]
    
    // Optional: Provide agent metadata
    func provideMetadata() -> AIAgentMetadata
    
    // Optional: Handle context updates
    func handleContextUpdate(_ context: AIContext)
}

TaskExecutable

The TaskExecutable protocol defines components that can execute tasks.

protocol TaskExecutable {
    // Execute a task and return a result
    func execute(task: AITask) -> AITaskResult
    
    // Optional: Check if task can be executed
    func canExecute(task: AITask) -> Bool
    
    // Optional: Provide task execution metadata
    func provideExecutionMetadata() -> TaskExecutionMetadata
}

ContextAware

The ContextAware protocol defines components that are aware of and can interact with context.

protocol ContextAware {
    // Get current context
    func getContext() -> AIContext?
    
    // Update context with new information
    func updateContext(_ context: AIContext)
    
    // Optional: Provide context-relevant information
    func provideContextualInformation() -> [String: Any]
}

HumanInteractive

The HumanInteractive protocol defines components that can interact with human users.

protocol HumanInteractive {
    // Request input from human user
    func requestHumanInput(prompt: String) -> String?
    
    // Provide output to human user
    func provideOutput(message: String)
    
    // Optional: Check if human interaction is available
    func isHumanInteractionAvailable() -> Bool
}

Code Examples

Initializing and Configuring the Collaborator

import AICollaborator

// Initialize the collaborator instance
let collaborator = AICollaborator()

// Connect AI agent with required credentials
collaborator.connect(agentType: .llm, 
                     credentials: AICredentials(apiKey: "YOUR_API_KEY"))

// Register an agent
let myAgent = MyAIAgent()
let agentId = collaborator.register(agent: myAgent)

Implementing a Custom AI Agent

// Example of an AI agent implementing the Collaborator protocol
struct MyAIAgent: AICollaboratorAgent {
    func processTask(_ task: AITask) -> AITaskResult {
        // Task processing logic
        return AITaskResult(status: .completed, output: "Task result")
    }
    
    func provideCapabilities() -> [AICapability] {
        return [.codeGeneration, .textAnalysis]
    }
}

// Register with the collaborator
collaborator.register(agent: MyAIAgent())

Creating and Executing a Task

// Create a task
let task = CodeGenerationTask(
    description: "Create a Swift function to calculate factorial",
    constraints: ["Must be recursive", "Must handle negative numbers"],
    priority: .medium
)

// Execute the task
let result = collaborator.execute(task: task)

// Process the result
switch result.status {
case .completed:
    print("Task completed: \(result.output)")
case .failed:
    print("Task failed: \(result.error?.localizedDescription ?? "Unknown error")")
case .partiallyCompleted:
    print("Task partially completed: \(result.output)")
}

Managing Context

// Get context for a session
if let context = collaborator.getContext(sessionId: sessionId) {
    // Store information in context
    context.store(key: "language", value: "Swift")
    
    // Retrieve information from context
    if let language = context.retrieve(key: "language") as? String {
        print("Current language: \(language)")
    }
    
    // Update context
    context.update(key: "language", value: "Swift 6")
    
    // Clear specific values
    context.clear(keys: ["temporary_data"])
}

AI-Readable Documentation

{
  "api_version": "0.1.0",
  "core_components": [
    {
      "name": "AICollaborator",
      "type": "class",
      "purpose": "Main framework entry point",
      "methods": [
        {"name": "connect", "signature": "func connect(agentType: AIAgentType, credentials: AICredentials) -> Bool"},
        {"name": "register", "signature": "func register(agent: AICollaboratorAgent) -> UUID"},
        {"name": "execute", "signature": "func execute(task: AITask) -> AITaskResult"},
        {"name": "getContext", "signature": "func getContext(sessionId: UUID) -> AIContext?"}
      ]
    },
    {
      "name": "AITask",
      "type": "protocol",
      "purpose": "Task representation",
      "methods": [
        {"name": "parseFromInput", "signature": "static func parseFromInput(_ input: String) -> AITask?"},
        {"name": "validate", "signature": "func validate() -> Bool"},
        {"name": "matchesCapabilities", "signature": "func matchesCapabilities(_ capabilities: [AICapability]) -> Bool"}
      ],
      "properties": [
        {"name": "id", "type": "UUID"},
        {"name": "type", "type": "AITaskType"},
        {"name": "priority", "type": "TaskPriority"}
      ]
    },
    {
      "name": "AIAgent",
      "type": "protocol",
      "purpose": "Agent interface",
      "methods": [
        {"name": "processTask", "signature": "func processTask(_ task: AITask) -> AITaskResult"},
        {"name": "provideCapabilities", "signature": "func provideCapabilities() -> [AICapability]"},
        {"name": "canHandle", "signature": "func canHandle(task: AITask) -> Bool"}
      ],
      "properties": [
        {"name": "id", "type": "UUID"},
        {"name": "type", "type": "AIAgentType"},
        {"name": "name", "type": "String"}
      ]
    },
    {
      "name": "AIContext",
      "type": "class",
      "purpose": "Context management",
      "methods": [
        {"name": "store", "signature": "func store(key: String, value: Any) -> Bool"},
        {"name": "retrieve", "signature": "func retrieve(key: String) -> Any?"},
        {"name": "update", "signature": "func update(key: String, value: Any) -> Bool"},
        {"name": "clear", "signature": "func clear(keys: [String]? = nil) -> Bool"},
        {"name": "getConversationHistory", "signature": "func getConversationHistory() -> [AIMessage]"}
      ]
    }
  ],
  "protocols": [
    {
      "name": "AICollaboratorAgent",
      "purpose": "Interface for AI agents",
      "required_methods": [
        "processTask",
        "provideCapabilities"
      ],
      "optional_methods": [
        "provideMetadata",
        "handleContextUpdate"
      ]
    },
    {
      "name": "TaskExecutable",
      "purpose": "Interface for task execution",
      "required_methods": [
        "execute"
      ],
      "optional_methods": [
        "canExecute",
        "provideExecutionMetadata"
      ]
    },
    {
      "name": "ContextAware",
      "purpose": "Interface for context-aware components",
      "required_methods": [
        "getContext",
        "updateContext"
      ],
      "optional_methods": [
        "provideContextualInformation"
      ]
    },
    {
      "name": "HumanInteractive",
      "purpose": "Interface for human interaction",
      "required_methods": [
        "requestHumanInput",
        "provideOutput"
      ],
      "optional_methods": [
        "isHumanInteractionAvailable"
      ]
    }
  ]
}

The API documentation above provides detailed information about the AICollaborator framework's components, protocols, and interfaces. For additional information or specific use cases, please refer to the Example implementations and Implementation Guide.