API Reference

API Reference

This document provides detailed API reference for FinchBot's core classes and methods.

Table of Contents

1. Agent Module
2. Memory Module
3. Tools Module
4. Skill Module
5. Channel Module
6. Config Module
7. I18n Module
8. Providers Module

1. Agent Module (finchbot.agent)

1.1 AgentFactory

Factory class for assembling and configuring Agent instances.

class AgentFactory:
    @staticmethod
    def create_for_cli(
        model: BaseChatModel,
        workspace: Path,
        session_id: str,
        config: Config,
        session_metadata_store: SessionMetadataStore | None = None,
    ) -> tuple[CompiledStateGraph, SqliteSaver | MemorySaver, list[BaseTool]]:

Parameters:

• model: Base chat model instance
• workspace: Workspace directory path
• session_id: Session ID
• config: Configuration object
• session_metadata_store: Session metadata store (optional)

Returns:

• (agent, checkpointer, tools) tuple

1.2 create_finch_agent

Creates and configures a FinchBot agent instance.

async def create_finch_agent(
    model: BaseChatModel,
    workspace: Path,
    tools: Sequence[BaseTool] | None = None,
    use_persistent: bool = True,
) -> tuple[CompiledStateGraph, AsyncSqliteSaver | MemorySaver]:

Parameters:

• model: Base chat model instance (e.g., ChatOpenAI, ChatAnthropic)
• workspace: Workspace directory path (Path object)
• tools: Available tools sequence (optional, defaults to None)
• use_persistent: Whether to enable persistent storage (Checkpointing)

Returns:

• (agent, checkpointer) tuple:
  • agent: Compiled LangGraph state graph
  • checkpointer: Persistent storage object

Example:

import asyncio
from pathlib import Path
from langchain_openai import ChatOpenAI
from finchbot.agent import create_finch_agent

async def main():
    model = ChatOpenAI(model="gpt-4")
    workspace = Path("./workspace")
    agent, checkpointer = await create_finch_agent(model, workspace)

    response = await agent.ainvoke(
        {"messages": [("user", "Hello!")]}, 
        config={"configurable": {"thread_id": "1"}}
    )

if __name__ == "__main__":
    asyncio.run(main())

1.3 ContextBuilder

Dynamic system prompt builder.

class ContextBuilder:
    def __init__(self, workspace: Path): ...
    
    def build_system_prompt(self, skill_names, use_cache=True) -> str: ...

Methods:

• build_system_prompt(): Generates complete system prompt string

Prompt Components:

• SYSTEM.md: Base role definition
• MEMORY_GUIDE.md: Memory usage guidelines
• SOUL.md: Soul definition (personality)
• AGENT_CONFIG.md: Agent configuration
• SKILL.md: Dynamically loaded skill descriptions
• TOOLS.md: Auto-generated tool documentation
• Runtime info (OS, Time, Python Version)

1.4 get_sqlite_checkpointer

Gets SQLite persistence checkpoint.

def get_sqlite_checkpointer(db_path: Path) -> SqliteSaver:

Parameters:

• db_path: SQLite database file path

Returns:

• SqliteSaver instance

2. Memory Module (finchbot.memory)

2.1 MemoryManager

Unified entry point for the memory system.

class MemoryManager:
    def __init__(
        self, 
        workspace: Path, 
        embedding_model: str = "BAAI/bge-small-zh-v1.5"
    ): ...

remember

Save a new memory.

def remember(
    self,
    content: str,
    category: str | None = None,
    importance: float | None = None,
    tags: list[str] | None = None,
) -> str:

Parameters:

• content: Memory text content
• category: Category (optional, e.g., "personal", "work")
• importance: Importance score (0.0-1.0, optional)
• tags: Tag list (optional)

Returns:

• memory_id: Newly created memory ID (UUID)

recall

Retrieve relevant memories.

def recall(
    self,
    query: str,
    top_k: int = 5,
    category: str | None = None,
    query_type: QueryType = QueryType.COMPLEX,
    similarity_threshold: float = 0.5,
    include_archived: bool = False,
) -> list[dict[str, Any]]:

Parameters:

• query: Query text (natural language)
• top_k: Number of results to return (default 5)
• category: Filter by category (optional)
• query_type: Query type (default QueryType.COMPLEX)
• similarity_threshold: Similarity threshold (default 0.5)
• include_archived: Whether to include archived memories (default False)

QueryType Enum:

Returns:

• List of memory dictionaries, each containing id, content, category, importance, similarity, etc.

forget

Delete or archive memories.

def forget(self, pattern: str) -> dict[str, Any]:

Parameters:

• pattern: String to match memory content

Returns:

• Deletion statistics dictionary

Other Methods

def get_stats(self) -> dict: ...
def search_memories(self, query: str, ...) -> list[dict]: ...
def get_recent_memories(self, days: int = 7, limit: int = 20) -> list[dict]: ...
def get_important_memories(self, min_importance: float = 0.8, limit: int = 20) -> list[dict]: ...

Usage Example

from finchbot.memory import MemoryManager, QueryType
from pathlib import Path

manager = MemoryManager(Path.home() / ".finchbot" / "workspace")

memory = manager.remember(
    content="User prefers dark theme",
    category="preference",
    importance=0.8
)

results = manager.recall(
    query="user interface preferences",
    query_type=QueryType.CONCEPTUAL,
    top_k=5
)

stats = manager.forget("old email")

2.2 QueryType

Query type enumeration.

class QueryType(StrEnum):
    KEYWORD_ONLY = "keyword_only"
    SEMANTIC_ONLY = "semantic_only"
    FACTUAL = "factual"
    CONCEPTUAL = "conceptual"
    COMPLEX = "complex"
    AMBIGUOUS = "ambiguous"

3. Tools Module (finchbot.tools)

3.1 FinchTool (Base Class)

Base class for all tools.

class FinchTool(BaseTool):
    name: str
    description: str
    parameters: ClassVar[dict[str, Any]]
    
    def _run(self, *args, **kwargs) -> Any: ...
    async def _arun(self, *args, **kwargs) -> Any: ...

3.2 ToolFactory

Tool factory class.

class ToolFactory:
    @staticmethod
    def create_default_tools(
        workspace: Path,
        config: Config,
        session_metadata_store: SessionMetadataStore | None = None,
    ) -> list[BaseTool]:

Parameters:

• workspace: Workspace directory path
• config: Configuration object
• session_metadata_store: Session metadata store (optional)

Returns:

• List of tools

3.3 ToolRegistry

Tool registry (singleton pattern).

class ToolRegistry:
    _instance: ClassVar[ToolRegistry | None] = None
    _tools: dict[str, BaseTool]
    
    @classmethod
    def get_instance(cls) -> ToolRegistry: ...
    
    def register(self, tool: BaseTool) -> None: ...
    def get(self, name: str) -> BaseTool | None: ...
    def list_tools(self) -> list[str]: ...
    def get_all_tools(self) -> list[BaseTool]: ...

3.4 Creating Custom Tools

from finchbot.tools.base import FinchTool
from typing import Any, ClassVar

class MyCustomTool(FinchTool):
    """Custom tool example."""
    
    name: str = "my_custom_tool"
    description: str = "My custom tool description"
    parameters: ClassVar[dict[str, Any]] = {
        "type": "object",
        "properties": {
            "input_text": {
                "type": "string",
                "description": "Input text"
            }
        },
        "required": ["input_text"]
    }
    
    def _run(self, input_text: str) -> str:
        return f"Result: {input_text}"

3.5 Built-in Tools

4. Skill Module (finchbot.agent.skills)

4.1 SkillsLoader

Skill loader.

class SkillsLoader:
    def __init__(self, workspace: Path): ...
    
    def list_skills(self, use_cache: bool = True) -> list[dict]: ...
    def load_skill(self, name: str, use_cache: bool = True) -> str | None: ...
    def get_always_skills(self) -> list[str]: ...
    def build_skills_summary(self) -> str: ...

Methods:

• list_skills(): Scan and list all available skills
• load_skill(): Load specified skill content
• get_always_skills(): Get all always-on skills
• build_skills_summary(): Build XML format skill summary

4.2 Skill File Format

---
name: skill-name
description: Skill description
metadata:
  finchbot:
    emoji: ✨
    always: false
    requires:
      bins: [curl, jq]
      env: [API_KEY]
---
# Skill content (Markdown)

5. Channel Module (finchbot.channels)

5.1 BaseChannel

Abstract base class for channels.

class BaseChannel(ABC):
    @abstractmethod
    async def start(self) -> None: ...
    
    @abstractmethod
    async def stop(self) -> None: ...
    
    @abstractmethod
    async def send(self, message: OutboundMessage) -> None: ...
    
    @abstractmethod
    async def receive(self) -> AsyncGenerator[InboundMessage, None]: ...

5.2 MessageBus

Async message router.

class MessageBus:
    def __init__(self): ...
    
    @property
    def inbound(self) -> asyncio.Queue[InboundMessage]: ...
    
    @property
    def outbound(self) -> asyncio.Queue[OutboundMessage]: ...
    
    async def publish_inbound(self, message: InboundMessage) -> None: ...
    async def publish_outbound(self, message: OutboundMessage) -> None: ...
    async def consume_inbound(self) -> AsyncGenerator[InboundMessage, None]: ...
    async def consume_outbound(self) -> AsyncGenerator[OutboundMessage, None]: ...

5.3 ChannelManager

Channel manager.

class ChannelManager:
    def __init__(self, bus: MessageBus): ...
    
    def register_channel(self, channel: BaseChannel) -> None: ...
    def unregister_channel(self, channel_id: str) -> None: ...
    async def start_all(self) -> None: ...
    async def stop_all(self) -> None: ...

5.4 Message Models

class InboundMessage(BaseModel):
    """Inbound message"""
    channel_id: str
    user_id: str
    content: str
    session_id: str | None = None
    metadata: dict = {}

class OutboundMessage(BaseModel):
    """Outbound message"""
    channel_id: str
    user_id: str
    content: str
    session_id: str | None = None
    metadata: dict = {}

6. Config Module (finchbot.config)

6.1 Config (Root Config)

class Config(BaseSettings):
    language: str = "en-US"
    language_set_by_user: bool = False
    default_model: str = "gpt-5"
    default_model_set_by_user: bool = False
    agents: AgentsConfig = Field(default_factory=AgentsConfig)
    providers: ProvidersConfig = Field(default_factory=ProvidersConfig)
    tools: ToolsConfig = Field(default_factory=ToolsConfig)

6.2 load_config

Load configuration.

def load_config() -> Config: ...

Description:

• Automatically merges default config, ~/.finchbot/config.json, and environment variables
• Environment variables have highest priority (prefix FINCHBOT_)

6.3 Configuration Structure

Config (Root)
├── language
├── default_model
├── agents
│   └── defaults
├── providers
│   ├── openai
│   ├── anthropic
│   ├── deepseek
│   ├── moonshot
│   ├── dashscope
│   ├── groq
│   ├── gemini
│   ├── openrouter
│   └── custom
└── tools
    ├── web.search
    ├── exec
    └── restrict_to_workspace

7. I18n Module (finchbot.i18n)

7.1 I18nLoader

Internationalization loader.

class I18nLoader:
    def __init__(self, locale: str = "en-US"): ...
    
    def get(self, key: str, default: str = "") -> str: ...
    def t(self, key: str, **kwargs) -> str: ...

Methods:

• get(): Get translated text
• t(): Get translated text with variable substitution

Example:

from finchbot.i18n import I18nLoader

i18n = I18nLoader("en-US")

text = i18n.get("cli.help")
text = i18n.t("cli.chat.session", session_id="abc123")

7.2 Supported Languages

8. Providers Module (finchbot.providers)

8.1 create_chat_model

Create chat model.

def create_chat_model(
    provider: str,
    model: str,
    config: Config,
) -> BaseChatModel:

Parameters:

• provider: Provider name
• model: Model name
• config: Configuration object

Returns:

• BaseChatModel instance

8.2 Supported Providers

8.3 Usage Example

from finchbot.providers import create_chat_model
from finchbot.config import load_config

config = load_config()

model = create_chat_model(
    provider="openai",
    model="gpt-5",
    config=config,
)