ai-bot-framework 0.1.0__tar.gz

ai_bot_framework-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+*.egg-info/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.agent-branch
+.todoist.yaml
+.env
+.claude/devops.yaml

ai_bot_framework-0.1.0/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: ai-bot-framework
+Version: 0.1.0
+Summary: AI agent framework with tool system and memory management
+Author-email: Vladimir Sumarokov <sumarokov.vp@gmail.com>
+Requires-Python: >=3.13
+Requires-Dist: anthropic>=0.52.0
+Requires-Dist: psycopg>=3.3.2
+Requires-Dist: pydantic>=2.11.0
+Requires-Dist: redis>=7.1.1
+Provides-Extra: claude-sdk
+Requires-Dist: claude-code-sdk>=0.0.25; extra == 'claude-sdk'

ai_bot_framework-0.1.0/pyproject.toml

@@ -0,0 +1,102 @@
+[project]
+name = "ai-bot-framework"
+version = "0.1.0"
+description = "AI agent framework with tool system and memory management"
+authors = [
+    { name = "Vladimir Sumarokov", email = "sumarokov.vp@gmail.com" }
+]
+requires-python = ">=3.13"
+dependencies = [
+    "pydantic>=2.11.0",
+    "anthropic>=0.52.0",
+    "psycopg>=3.3.2",
+    "redis>=7.1.1",
+]
+
+[project.optional-dependencies]
+claude-sdk = [
+    "claude-code-sdk>=0.0.25",
+]
+
+[dependency-groups]
+dev = [
+    "import-linter>=2.9",
+    "mypy>=1.18.2",
+    "pyright>=1.1.406",
+    "pytest>=9.0.0",
+    "ruff>=0.13.3",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ai_framework"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/ai_framework/", "pyproject.toml"]
+
+[tool.pyright]
+venv = ".venv"
+venvPath = "."
+reportUnusedVariable = false
+reportUnusedImport = false
+reportMissingImports = false
+
+[tool.ruff]
+lint.select = [
+  "F",   # flake8
+  "E",   # pycodestyle errors
+  "W",   # pycodestyle warnings
+  "B",   # flake8-bugbear
+  "N",   # PEP 8 naming conventions
+  "C",   # McCabe complexity
+  "T",   # Print found todos
+  "UP",  # upgrade syntax
+  "ANN", # type annotations
+  "S",   # security issues
+  "DTZ", # datetime timezone issues
+]
+
+lint.ignore = [
+  "ANN204", # Missing type annotation for special methods
+  "E501",   # line too long
+  "C901",   # function too complex
+  "ANN401", # Any type
+  "W293",   # blank line contains whitespace
+  "W291",   # trailing whitespace
+]
+
+[tool.ruff.lint.per-file-ignores]
+"test*" = [
+  "S101",   # disable security issues for tests
+  "ANN201", # Missing return type
+]
+
+[tool.mypy]
+exclude = [".venv/"]
+ignore_missing_imports = true
+strict = false
+disallow_subclassing_any = true
+warn_unused_ignores = false
+warn_redundant_casts = true
+check_untyped_defs = true
+disallow_untyped_decorators = true
+show_error_codes = true
+
+[tool.importlinter]
+root_packages = ["ai_framework"]
+
+[[tool.importlinter.contracts]]
+name = "ai_framework layers"
+type = "layers"
+layers = [
+    "ai_framework.integrations",
+    "ai_framework.application",
+    "ai_framework.providers",
+    "ai_framework.tools",
+    "ai_framework.memory",
+    "ai_framework.protocols",
+    "ai_framework.entities",
+]

ai_bot_framework-0.1.0/src/ai_framework/__init__.py

@@ -0,0 +1,29 @@
+from ai_framework.application import AIApplication
+from ai_framework.entities import (
+    AIResponse,
+    Message,
+    TokenUsage,
+    ToolCall,
+    ToolResult,
+)
+from ai_framework.integrations.bot_framework import AIStep
+from ai_framework.protocols import (
+    IAIProvider,
+    IMemoryStore,
+    IToolRegistry,
+    ToolDefinition,
+)
+
+__all__ = [
+    "AIApplication",
+    "AIResponse",
+    "AIStep",
+    "IAIProvider",
+    "IMemoryStore",
+    "IToolRegistry",
+    "Message",
+    "TokenUsage",
+    "ToolCall",
+    "ToolDefinition",
+    "ToolResult",
+]

ai_bot_framework-0.1.0/src/ai_framework/application.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+from ai_framework.entities.ai_response import AIResponse
+from ai_framework.entities.message import Message
+from ai_framework.entities.tool import ToolResult
+from ai_framework.protocols.i_ai_provider import IAIProvider
+from ai_framework.protocols.i_memory_store import IMemoryStore
+from ai_framework.protocols.i_tool_registry import IToolRegistry
+
+
+class AIApplication:
+    def __init__(
+        self,
+        provider: IAIProvider,
+        memory: IMemoryStore,
+        tool_registry: IToolRegistry | None = None,
+        system_prompt: str | None = None,
+        max_tool_rounds: int = 10,
+    ) -> None:
+        self._provider = provider
+        self._memory = memory
+        self._tool_registry = tool_registry
+        self._system_prompt = system_prompt
+        self._max_tool_rounds = max_tool_rounds
+
+    def process_message(self, thread_id: str, user_message: str) -> AIResponse:
+        user_msg = Message(role="user", content=user_message)
+        self._memory.add_message(thread_id, user_msg)
+
+        tools = self._tool_registry.get_definitions() if self._tool_registry else None
+
+        for _ in range(self._max_tool_rounds):
+            messages = self._memory.get_messages(thread_id)
+            response = self._provider.send_message(
+                messages=messages,
+                system=self._system_prompt,
+                tools=tools,
+            )
+
+            if not response.tool_calls:
+                break
+
+            assistant_msg = Message(
+                role="assistant",
+                content=response.content or "",
+                tool_calls=response.tool_calls,
+            )
+            self._memory.add_message(thread_id, assistant_msg)
+
+            tool_results = self._execute_tool_calls(response)
+            tool_msg = Message(
+                role="user",
+                content="",
+                tool_results=tool_results,
+            )
+            self._memory.add_message(thread_id, tool_msg)
+        else:
+            raise RuntimeError(
+                f"Tool loop exceeded {self._max_tool_rounds} rounds"
+            )
+
+        assistant_msg = Message(
+            role="assistant",
+            content=response.content or "",
+        )
+        self._memory.add_message(thread_id, assistant_msg)
+        return response
+
+    def _execute_tool_calls(self, response: AIResponse) -> list[ToolResult]:
+        if not self._tool_registry:
+            raise ValueError("Tool registry is required to execute tool calls")
+
+        results: list[ToolResult] = []
+        for tool_call in response.tool_calls:
+            result = self._tool_registry.execute(
+                tool_call.name, tool_call.arguments, tool_call.id
+            )
+            results.append(result)
+        return results

ai_bot_framework-0.1.0/src/ai_framework/entities/__init__.py

@@ -0,0 +1,12 @@
+from ai_framework.entities.ai_response import AIResponse
+from ai_framework.entities.message import Message
+from ai_framework.entities.token_usage import TokenUsage
+from ai_framework.entities.tool import ToolCall, ToolResult
+
+__all__ = [
+    "AIResponse",
+    "Message",
+    "TokenUsage",
+    "ToolCall",
+    "ToolResult",
+]

ai_bot_framework-0.1.0/src/ai_framework/entities/ai_response.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+from ai_framework.entities.token_usage import TokenUsage
+from ai_framework.entities.tool import ToolCall
+
+
+class AIResponse(BaseModel):
+    content: str | None = None
+    tool_calls: list[ToolCall] = []
+    stop_reason: str | None = None
+    usage: TokenUsage | None = None

ai_bot_framework-0.1.0/src/ai_framework/entities/message.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel
+
+from ai_framework.entities.tool import ToolCall, ToolResult
+
+
+class Message(BaseModel):
+    role: Literal["user", "assistant", "system"]
+    content: str
+    tool_calls: list[ToolCall] | None = None
+    tool_results: list[ToolResult] | None = None

ai_bot_framework-0.1.0/src/ai_framework/entities/token_usage.py

@@ -0,0 +1,6 @@
+from pydantic import BaseModel
+
+
+class TokenUsage(BaseModel):
+    input_tokens: int
+    output_tokens: int

ai_bot_framework-0.1.0/src/ai_framework/entities/tool.py

@@ -0,0 +1,13 @@
+from pydantic import BaseModel
+
+
+class ToolCall(BaseModel):
+    id: str
+    name: str
+    arguments: dict[str, object]
+
+
+class ToolResult(BaseModel):
+    tool_call_id: str
+    content: str
+    is_error: bool = False

ai_bot_framework-0.1.0/src/ai_framework/integrations/__init__.py

@@ -0,0 +1,5 @@
+from ai_framework.integrations.bot_framework import AIStep
+
+__all__ = [
+    "AIStep",
+]

ai_bot_framework-0.1.0/src/ai_framework/integrations/bot_framework.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any, Protocol
+
+from ai_framework.application import AIApplication
+
+type GetUserMessage = Callable[[Any], str | None]
+
+
+class IMessageSender(Protocol):
+    def send(
+        self,
+        chat_id: int,
+        text: str,
+        parse_mode: str = "HTML",
+        keyboard: Any = None,
+        flow_name: str | None = None,
+    ) -> Any: ...
+
+
+class IUser(Protocol):
+    @property
+    def id(self) -> int: ...
+
+
+class AIStep:
+    name: str = "ai"
+
+    def __init__(
+        self,
+        ai_application: AIApplication,
+        message_sender: IMessageSender,
+        get_user_message: GetUserMessage | None = None,
+    ) -> None:
+        self._ai_application = ai_application
+        self._message_sender = message_sender
+        self._get_user_message = get_user_message or _default_get_user_message
+
+    def execute(self, user: IUser, state: Any) -> bool:
+        text = self._get_user_message(state)
+        if not text:
+            return True
+
+        thread_id = str(user.id)
+        response = self._ai_application.process_message(thread_id, text)
+        if response.content:
+            self._message_sender.send(user.id, response.content)
+        return False
+
+
+def _default_get_user_message(state: Any) -> str | None:
+    if hasattr(state, "source_message"):
+        msg = state.source_message
+        if hasattr(msg, "text"):
+            return msg.text  # type: ignore[no-any-return]
+    return None

ai_bot_framework-0.1.0/src/ai_framework/memory/__init__.py

@@ -0,0 +1,9 @@
+from ai_framework.memory.in_memory_store import InMemoryStore
+from ai_framework.memory.postgres_memory_store import PostgresMemoryStore
+from ai_framework.memory.redis_memory_store import RedisMemoryStore
+
+__all__ = [
+    "InMemoryStore",
+    "PostgresMemoryStore",
+    "RedisMemoryStore",
+]

ai_bot_framework-0.1.0/src/ai_framework/memory/in_memory_store.py

@@ -0,0 +1,17 @@
+from ai_framework.entities.message import Message
+
+
+class InMemoryStore:
+    def __init__(self) -> None:
+        self._store: dict[str, list[Message]] = {}
+
+    def get_messages(self, thread_id: str) -> list[Message]:
+        return list(self._store.get(thread_id, []))
+
+    def add_message(self, thread_id: str, message: Message) -> None:
+        if thread_id not in self._store:
+            self._store[thread_id] = []
+        self._store[thread_id].append(message)
+
+    def clear(self, thread_id: str) -> None:
+        self._store.pop(thread_id, None)

ai_bot_framework-0.1.0/src/ai_framework/memory/postgres_memory_store.py

@@ -0,0 +1,81 @@
+import json
+from typing import Any
+
+import psycopg
+
+from ai_framework.entities.message import Message
+from ai_framework.entities.tool import ToolCall, ToolResult
+
+
+class PostgresMemoryStore:
+    def __init__(self, database_url: str) -> None:
+        self._database_url = database_url
+        self._conn: psycopg.Connection[Any] | None = None
+
+    def open(self) -> None:
+        self._conn = psycopg.connect(self._database_url)
+
+    def close(self) -> None:
+        if self._conn:
+            self._conn.close()
+            self._conn = None
+
+    @property
+    def _connection(self) -> psycopg.Connection[Any]:
+        if not self._conn:
+            raise RuntimeError("Connection is not open. Call open() first.")
+        return self._conn
+
+    def get_messages(self, thread_id: str) -> list[Message]:
+        cursor = self._connection.execute(
+            "SELECT role, content, tool_calls, tool_results "
+            "FROM ai_messages WHERE thread_id = %s ORDER BY id",
+            (thread_id,),
+        )
+        messages: list[Message] = []
+        rows: list[Any] = cursor.fetchall()
+        for role, content, tool_calls_json, tool_results_json in rows:
+            tool_calls = (
+                [ToolCall(**tc) for tc in tool_calls_json]
+                if tool_calls_json
+                else None
+            )
+            tool_results = (
+                [ToolResult(**tr) for tr in tool_results_json]
+                if tool_results_json
+                else None
+            )
+            messages.append(
+                Message(
+                    role=role,
+                    content=str(content),
+                    tool_calls=tool_calls,
+                    tool_results=tool_results,
+                )
+            )
+        return messages
+
+    def add_message(self, thread_id: str, message: Message) -> None:
+        tool_calls_json = (
+            json.dumps([tc.model_dump() for tc in message.tool_calls])
+            if message.tool_calls
+            else None
+        )
+        tool_results_json = (
+            json.dumps([tr.model_dump() for tr in message.tool_results])
+            if message.tool_results
+            else None
+        )
+        self._connection.execute(
+            "INSERT INTO ai_messages (thread_id, role, content, tool_calls, tool_results) "
+            "VALUES (%s, %s, %s, %s::jsonb, %s::jsonb)",
+            (thread_id, message.role, message.content, tool_calls_json, tool_results_json),
+        )
+        self._connection.commit()
+
+    def clear(self, thread_id: str) -> None:
+        self._connection.execute(
+            "DELETE FROM ai_messages WHERE thread_id = %s",
+            (thread_id,),
+        )
+        self._connection.commit()

ai_bot_framework-0.1.0/src/ai_framework/memory/redis_memory_store.py

@@ -0,0 +1,23 @@
+from typing import Any
+
+import redis
+
+from ai_framework.entities.message import Message
+
+
+class RedisMemoryStore:
+    def __init__(self, redis_url: str) -> None:
+        self._client = redis.Redis.from_url(redis_url)
+
+    def _key(self, thread_id: str) -> str:
+        return f"ai:messages:{thread_id}"
+
+    def get_messages(self, thread_id: str) -> list[Message]:
+        raw_messages: Any = self._client.lrange(self._key(thread_id), 0, -1)
+        return [Message.model_validate_json(raw) for raw in raw_messages]
+
+    def add_message(self, thread_id: str, message: Message) -> None:
+        self._client.rpush(self._key(thread_id), message.model_dump_json())
+
+    def clear(self, thread_id: str) -> None:
+        self._client.delete(self._key(thread_id))

ai_bot_framework-0.1.0/src/ai_framework/protocols/__init__.py

@@ -0,0 +1,11 @@
+from ai_framework.protocols.i_ai_provider import IAIProvider
+from ai_framework.protocols.i_memory_store import IMemoryStore
+from ai_framework.protocols.i_tool_registry import IToolRegistry
+from ai_framework.protocols.tool_definition import ToolDefinition
+
+__all__ = [
+    "IAIProvider",
+    "IMemoryStore",
+    "IToolRegistry",
+    "ToolDefinition",
+]

ai_bot_framework-0.1.0/src/ai_framework/protocols/i_ai_provider.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from typing import Protocol
+
+from ai_framework.entities.ai_response import AIResponse
+from ai_framework.entities.message import Message
+from ai_framework.protocols.tool_definition import ToolDefinition
+
+
+class IAIProvider(Protocol):
+    def send_message(
+        self,
+        messages: list[Message],
+        system: str | None = None,
+        tools: list[ToolDefinition] | None = None,
+    ) -> AIResponse: ...

ai_bot_framework-0.1.0/src/ai_framework/protocols/i_memory_store.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from typing import Protocol
+
+from ai_framework.entities.message import Message
+
+
+class IMemoryStore(Protocol):
+    def get_messages(self, thread_id: str) -> list[Message]: ...
+
+    def add_message(self, thread_id: str, message: Message) -> None: ...
+
+    def clear(self, thread_id: str) -> None: ...

ai_bot_framework-0.1.0/src/ai_framework/protocols/i_tool_registry.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from typing import Protocol
+
+from ai_framework.entities.tool import ToolResult
+from ai_framework.protocols.tool_definition import ToolDefinition
+
+
+class IToolRegistry(Protocol):
+    def register(self, tool: ToolDefinition) -> None: ...
+
+    def get_definitions(self) -> list[ToolDefinition]: ...
+
+    def execute(self, name: str, arguments: dict[str, object], tool_call_id: str) -> ToolResult: ...

ai_bot_framework-0.1.0/src/ai_framework/protocols/tool_definition.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict
+
+
+class ToolDefinition(BaseModel):
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    name: str
+    description: str
+    input_schema: dict[str, Any]
+    handler: Callable[..., Any] | None = None

ai_bot_framework-0.1.0/src/ai_framework/providers/__init__.py

@@ -0,0 +1,4 @@
+from ai_framework.providers.anthropic_provider import AnthropicProvider
+from ai_framework.providers.claude_sdk_provider import ClaudeSdkProvider
+
+__all__ = ["AnthropicProvider", "ClaudeSdkProvider"]

ai_bot_framework-0.1.0/src/ai_framework/providers/anthropic_provider.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+from typing import Any
+
+import anthropic
+
+from ai_framework.entities.ai_response import AIResponse
+from ai_framework.entities.message import Message
+from ai_framework.entities.token_usage import TokenUsage
+from ai_framework.entities.tool import ToolCall
+from ai_framework.protocols.tool_definition import ToolDefinition
+
+
+class AnthropicProvider:
+    def __init__(
+        self, api_key: str, model: str = "claude-sonnet-4-20250514"
+    ) -> None:
+        self._client = anthropic.Anthropic(api_key=api_key)
+        self._model = model
+
+    def send_message(
+        self,
+        messages: list[Message],
+        system: str | None = None,
+        tools: list[ToolDefinition] | None = None,
+    ) -> AIResponse:
+        kwargs: dict[str, Any] = {
+            "model": self._model,
+            "max_tokens": 8192,
+            "messages": [self._convert_message(m) for m in messages],
+        }
+
+        if system:
+            kwargs["system"] = system
+
+        if tools:
+            kwargs["tools"] = [self._convert_tool(t) for t in tools]
+
+        response = self._client.messages.create(**kwargs)
+
+        return self._convert_response(response)
+
+    def _convert_message(self, message: Message) -> dict[str, Any]:
+        if message.tool_results:
+            content: list[dict[str, Any]] = [
+                {
+                    "type": "tool_result",
+                    "tool_use_id": tr.tool_call_id,
+                    "content": tr.content,
+                    **({"is_error": True} if tr.is_error else {}),
+                }
+                for tr in message.tool_results
+            ]
+            return {"role": "user", "content": content}
+
+        if message.role == "assistant" and message.tool_calls:
+            content_blocks: list[dict[str, Any]] = []
+            if message.content:
+                content_blocks.append({"type": "text", "text": message.content})
+            for tc in message.tool_calls:
+                content_blocks.append(
+                    {
+                        "type": "tool_use",
+                        "id": tc.id,
+                        "name": tc.name,
+                        "input": tc.arguments,
+                    }
+                )
+            return {"role": "assistant", "content": content_blocks}
+
+        return {"role": message.role, "content": message.content}
+
+    def _convert_tool(self, tool: ToolDefinition) -> dict[str, Any]:
+        return {
+            "name": tool.name,
+            "description": tool.description,
+            "input_schema": tool.input_schema,
+        }
+
+    def _convert_response(self, response: anthropic.types.Message) -> AIResponse:
+        text_parts: list[str] = []
+        tool_calls: list[ToolCall] = []
+
+        for block in response.content:
+            if block.type == "text":
+                text_parts.append(block.text)
+            elif block.type == "tool_use":
+                tool_calls.append(
+                    ToolCall(
+                        id=block.id,
+                        name=block.name,
+                        arguments=dict(block.input),  # pyright: ignore[reportUnknownArgumentType]
+                    )
+                )
+
+        return AIResponse(
+            content="\n".join(text_parts) if text_parts else None,
+            tool_calls=tool_calls,
+            stop_reason=response.stop_reason,
+            usage=TokenUsage(
+                input_tokens=response.usage.input_tokens,
+                output_tokens=response.usage.output_tokens,
+            ),
+        )

ai_bot_framework-0.1.0/src/ai_framework/providers/claude_sdk_provider.py

@@ -0,0 +1,130 @@
+import asyncio
+from typing import Any, Literal
+
+from claude_code_sdk import (
+    AssistantMessage,
+    ClaudeCodeOptions,
+    ResultMessage,
+    TextBlock,
+    ToolUseBlock,
+    query,
+)
+
+from ai_framework.entities.ai_response import AIResponse
+from ai_framework.entities.message import Message
+from ai_framework.entities.token_usage import TokenUsage
+from ai_framework.entities.tool import ToolCall
+from ai_framework.protocols.tool_definition import ToolDefinition
+
+type PermissionMode = Literal["default", "acceptEdits", "plan", "bypassPermissions"]
+
+
+class ClaudeSdkProvider:
+    def __init__(
+        self,
+        model: str = "claude-sonnet-4-20250514",
+        cwd: str | None = None,
+        permission_mode: PermissionMode = "default",
+    ) -> None:
+        self._model = model
+        self._cwd = cwd
+        self._permission_mode: PermissionMode = permission_mode
+        self._last_session_id: str | None = None
+
+    @property
+    def last_session_id(self) -> str | None:
+        return self._last_session_id
+
+    def send_message(
+        self,
+        messages: list[Message],
+        system: str | None = None,
+        tools: list[ToolDefinition] | None = None,
+    ) -> AIResponse:
+        return asyncio.run(self._send_message_async(messages, system, tools))
+
+    async def _send_message_async(
+        self,
+        messages: list[Message],
+        system: str | None = None,
+        tools: list[ToolDefinition] | None = None,
+    ) -> AIResponse:
+        prompt = self._build_prompt(messages)
+
+        options = ClaudeCodeOptions(
+            model=self._model,
+            permission_mode=self._permission_mode,
+            resume=self._last_session_id,
+        )
+
+        if self._cwd:
+            options.cwd = self._cwd
+
+        if system:
+            options.system_prompt = system
+
+        if tools:
+            options.allowed_tools = [t.name for t in tools]
+
+        text_parts: list[str] = []
+        tool_calls: list[ToolCall] = []
+        usage: TokenUsage | None = None
+
+        async for msg in query(prompt=prompt, options=options):
+            if isinstance(msg, AssistantMessage):
+                for block in msg.content:
+                    if isinstance(block, TextBlock):
+                        text_parts.append(block.text)
+                    elif isinstance(block, ToolUseBlock):
+                        tool_calls.append(
+                            ToolCall(
+                                id=block.id,
+                                name=block.name,
+                                arguments=self._normalize_arguments(block.input),
+                            )
+                        )
+            elif isinstance(msg, ResultMessage):
+                self._last_session_id = msg.session_id
+                usage = self._extract_usage(msg)
+
+        return AIResponse(
+            content="\n".join(text_parts) if text_parts else None,
+            tool_calls=tool_calls,
+            stop_reason="end_turn",
+            usage=usage,
+        )
+
+    def _build_prompt(self, messages: list[Message]) -> str:
+        # claude-code-sdk query() accepts a single prompt string, not a messages list.
+        # When resuming a session, the SDK retains prior conversation context,
+        # so only the latest user message is needed.
+        # On a fresh session, we concatenate the full history to avoid context loss.
+        if self._last_session_id:
+            for msg in reversed(messages):
+                if msg.role == "user":
+                    return msg.content
+            return ""
+
+        parts: list[str] = []
+        for msg in messages:
+            prefix = "User" if msg.role == "user" else "Assistant"
+            parts.append(f"[{prefix}]: {msg.content}")
+        return "\n\n".join(parts)
+
+    def _normalize_arguments(
+        self, raw_input: dict[str, Any]
+    ) -> dict[str, object]:
+        return dict(raw_input)
+
+    def _extract_usage(self, result: ResultMessage) -> TokenUsage:
+        raw_usage = result.usage or {}
+        input_tokens = (
+            raw_usage.get("input_tokens", 0)
+            + raw_usage.get("cache_creation_input_tokens", 0)
+            + raw_usage.get("cache_read_input_tokens", 0)
+        )
+        output_tokens = raw_usage.get("output_tokens", 0)
+        return TokenUsage(
+            input_tokens=input_tokens,
+            output_tokens=output_tokens,
+        )

ai_bot_framework-0.1.0/src/ai_framework/tools/__init__.py

@@ -0,0 +1,4 @@
+from ai_framework.tools.decorators import tool
+from ai_framework.tools.tool_registry import ToolRegistry
+
+__all__ = ["ToolRegistry", "tool"]

ai_bot_framework-0.1.0/src/ai_framework/tools/decorators.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable
+from typing import Any, get_type_hints
+
+from pydantic import TypeAdapter
+
+from ai_framework.protocols.tool_definition import ToolDefinition
+
+_PYTHON_TYPE_TO_JSON: dict[type, str] = {
+    str: "string",
+    int: "integer",
+    float: "number",
+    bool: "boolean",
+}
+
+
+def _build_input_schema(func: Callable[..., Any]) -> dict[str, Any]:
+    hints = get_type_hints(func)
+    sig = inspect.signature(func)
+    properties: dict[str, Any] = {}
+    required: list[str] = []
+
+    for param_name, param in sig.parameters.items():
+        param_type = hints.get(param_name, str)
+
+        if param_type in _PYTHON_TYPE_TO_JSON:
+            prop: dict[str, Any] = {"type": _PYTHON_TYPE_TO_JSON[param_type]}
+        else:
+            adapter = TypeAdapter(param_type)
+            prop = adapter.json_schema()
+
+        properties[param_name] = prop
+
+        if param.default is inspect.Parameter.empty:
+            required.append(param_name)
+
+    schema: dict[str, Any] = {
+        "type": "object",
+        "properties": properties,
+    }
+    if required:
+        schema["required"] = required
+
+    return schema
+
+
+def tool(name: str, description: str) -> Callable[[Callable[..., Any]], ToolDefinition]:
+    def decorator(func: Callable[..., Any]) -> ToolDefinition:
+        input_schema = _build_input_schema(func)
+        return ToolDefinition(
+            name=name,
+            description=description,
+            input_schema=input_schema,
+            handler=func,
+        )
+
+    return decorator

ai_bot_framework-0.1.0/src/ai_framework/tools/tool_registry.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from ai_framework.entities.tool import ToolResult
+from ai_framework.protocols.tool_definition import ToolDefinition
+
+
+class ToolRegistry:
+    def __init__(self) -> None:
+        self._tools: dict[str, ToolDefinition] = {}
+
+    def register(self, tool: ToolDefinition) -> None:
+        self._tools[tool.name] = tool
+
+    def get_definitions(self) -> list[ToolDefinition]:
+        return list(self._tools.values())
+
+    def execute(self, name: str, arguments: dict[str, object], tool_call_id: str) -> ToolResult:
+        tool = self._tools[name]
+        if tool.handler is None:
+            raise ValueError(f"Tool '{name}' has no handler")
+        result = tool.handler(**arguments)
+        return ToolResult(
+            tool_call_id=tool_call_id,
+            content=str(result),
+        )