iil-chat-agent 0.1.0__tar.gz

iil_chat_agent-0.1.0/.gitignore

@@ -0,0 +1,50 @@
+# Python
+__pycache__/
+*.py[cod]
+*\.class
+.venv/
+venv/
+*.egg-info/
+dist/
+build/
+# Django
+*.log
+db.sqlite3
+media/
+staticfiles/
+# Environment
+.env
+.env.local
+.env.prod
+
+# Secrets (ADR-045) — NEVER commit plaintext
+secrets.env
+!secrets.enc.env
+# IDE
+.idea/
+.vscode/
+*.swp
+# OS
+.DS_Store
+Thumbs.db
+# Large files
+*.sqlite3
+*.log
+output_batch/
+app_backup/
+docs_legacy/
+# Sphinx build output
+docs/_build/
+*:Zone.Identifier
+# Local Windsurf/MCP config — machine-specific, never commit
+.windsurf/mcp_config.json
+# Local infra plaintext secrets — NEVER commit
+infra/*.env
+infra/*.key
+# Validate-ports CI draft (not yet integrated)
+.github/workflows/validate-ports.yml
+# Markdownlint local config override
+.markdownlint.json
+# Concept review drafts (local working copies, not for VCS)
+docs/concepts/REVIEW-*
+env_loader.py

iil_chat_agent-0.1.0/PKG-INFO

@@ -0,0 +1,54 @@
+Metadata-Version: 2.4
+Name: iil-chat-agent
+Version: 0.1.0
+Summary: Domain-agnostic chat agent with Tool-Use loop
+Author: Achim Dehnert
+License: MIT
+Requires-Python: >=3.11
+Requires-Dist: pydantic>=2.0
+Provides-Extra: creative
+Requires-Dist: creative-services>=0.1.0; extra == 'creative'
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.1; extra == 'dev'
+Provides-Extra: redis
+Requires-Dist: redis>=5.0; extra == 'redis'
+Description-Content-Type: text/markdown
+
+# chat-agent
+
+Domain-agnostic Chat Agent with Tool-Use loop — platform package per ADR-034 §3.
+
+## Core Components
+
+- **ChatAgent**: Core Tool-Use loop (LLM → tool calls → execute → LLM)
+- **DomainToolkit**: ABC for app-specific tool collections
+- **SessionBackend**: Protocol for pluggable session storage (InMemory, Redis)
+- **ToolkitRegistry**: Global registry for toolkit discovery
+
+## Installation
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Usage
+
+```python
+from chat_agent import ChatAgent, InMemorySessionBackend
+
+agent = ChatAgent(
+    toolkit=MyToolkit(),
+    completion=my_llm_client,
+    session_backend=InMemorySessionBackend(),
+    system_prompt="You are a helpful assistant.",
+)
+
+response = await agent.chat(
+    session_id="user-123",
+    user_message="How many rooms are on floor 2?",
+    tenant_id="tenant-abc",
+)
+```

iil_chat_agent-0.1.0/README.md

@@ -0,0 +1,35 @@
+# chat-agent
+
+Domain-agnostic Chat Agent with Tool-Use loop — platform package per ADR-034 §3.
+
+## Core Components
+
+- **ChatAgent**: Core Tool-Use loop (LLM → tool calls → execute → LLM)
+- **DomainToolkit**: ABC for app-specific tool collections
+- **SessionBackend**: Protocol for pluggable session storage (InMemory, Redis)
+- **ToolkitRegistry**: Global registry for toolkit discovery
+
+## Installation
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Usage
+
+```python
+from chat_agent import ChatAgent, InMemorySessionBackend
+
+agent = ChatAgent(
+    toolkit=MyToolkit(),
+    completion=my_llm_client,
+    session_backend=InMemorySessionBackend(),
+    system_prompt="You are a helpful assistant.",
+)
+
+response = await agent.chat(
+    session_id="user-123",
+    user_message="How many rooms are on floor 2?",
+    tenant_id="tenant-abc",
+)
+```

iil_chat_agent-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "iil-chat-agent"
+version = "0.1.0"
+description = "Domain-agnostic chat agent with Tool-Use loop"
+readme = "README.md"
+requires-python = ">=3.11"
+license = {text = "MIT"}
+authors = [{name = "Achim Dehnert"}]
+
+dependencies = [
+    "pydantic>=2.0",
+]
+
+[project.optional-dependencies]
+creative = ["creative-services>=0.1.0"]
+redis = ["redis>=5.0"]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "pytest-cov>=4.0",
+    "ruff>=0.1",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/chat_agent"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "strict"
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W"]
+ignore = ["E501"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["chat_agent"]

iil_chat_agent-0.1.0/src/chat_agent/__init__.py

@@ -0,0 +1,46 @@
+"""chat-agent — Domain-agnostic Chat Agent with Tool-Use loop.
+
+Platform package per ADR-034 §3. Provides:
+- ChatAgent: Core Tool-Use loop (LLM → tool calls → execute → LLM)
+- DomainToolkit: ABC for app-specific tool collections
+- SessionBackend: Protocol for pluggable session storage
+- ToolkitRegistry: Global registry for toolkit discovery
+"""
+
+__version__ = "0.1.0"
+
+from .agent import ChatAgent, CompletionBackend
+from .models import (
+    AgentContext,
+    AgentResponse,
+    ChatMessage,
+    ChatSession,
+    ToolResult,
+)
+from .session import (
+    InMemorySessionBackend,
+    RedisSessionBackend,
+    SessionBackend,
+)
+from .composite import CompositeToolkit
+from .toolkit import DomainToolkit
+
+__all__ = [
+    "__version__",
+    # Agent
+    "ChatAgent",
+    "CompletionBackend",
+    # Models
+    "AgentContext",
+    "AgentResponse",
+    "ChatMessage",
+    "ChatSession",
+    "ToolResult",
+    # Toolkit
+    "CompositeToolkit",
+    "DomainToolkit",
+    # Session
+    "SessionBackend",
+    "InMemorySessionBackend",
+    "RedisSessionBackend",
+]

iil_chat_agent-0.1.0/src/chat_agent/agent.py

@@ -0,0 +1,243 @@
+"""ChatAgent — domain-agnostic Tool-Use agent.
+
+The core loop: user message → LLM → (tool calls → execute → LLM)* → response.
+
+Decoupled from any specific LLM client via the CompletionBackend protocol.
+Apps provide domain logic via DomainToolkit.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from dataclasses import dataclass
+from typing import Any, Protocol, runtime_checkable
+
+from .models import AgentContext, AgentResponse, ChatSession, ToolResult
+from .session import SessionBackend
+from .toolkit import DomainToolkit
+
+logger = logging.getLogger(__name__)
+
+
+@runtime_checkable
+class CompletionBackend(Protocol):
+    """Protocol for LLM completion with tool-use.
+
+    Matches creative_services.DynamicLLMClient.complete() signature.
+    """
+
+    async def complete(
+        self,
+        messages: list[dict[str, Any]],
+        tools: list[dict[str, Any]] | None = None,
+        tool_choice: str = "auto",
+        **kwargs: Any,
+    ) -> Any:
+        """Call LLM with messages and optional tools.
+
+        Must return an object with:
+        - content: str | None
+        - tool_calls: list with .id, .name, .arguments
+        - has_tool_calls: bool
+        """
+        ...
+
+
+@dataclass
+class ChatAgent:
+    """Domain-agnostic Tool-Use agent.
+
+    Extracted from travel-beat ConversationalTripAgent,
+    generalized for all apps per ADR-034 §3.
+
+    Usage::
+
+        agent = ChatAgent(
+            toolkit=CADToolkit(db_pool),
+            completion=DynamicLLMClient(registry),
+            session_backend=RedisSessionBackend(redis),
+            system_prompt="You are a CAD assistant...",
+        )
+        response = await agent.chat(
+            session_id="cad-user-123",
+            user_message="Wie viele tragende Wände im 2.OG?",
+            user=request.user,
+        )
+    """
+
+    toolkit: DomainToolkit
+    completion: CompletionBackend
+    session_backend: SessionBackend
+    system_prompt: str
+    max_rounds: int = 10
+    action_code: str = "chat"
+
+    async def chat(
+        self,
+        session_id: str,
+        user_message: str,
+        *,
+        user: Any = None,
+        tenant_id: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> AgentResponse:
+        """Process a user message through the Tool-Use loop.
+
+        Args:
+            session_id: Unique session identifier.
+            user_message: The user's natural language input.
+            user: Authenticated user object (passed to tools).
+            tenant_id: Tenant ID for multi-tenant isolation.
+            metadata: Additional context for tool execution.
+
+        Returns:
+            AgentResponse with the final text and stats.
+        """
+        session = await self.session_backend.load(session_id)
+        if session is None:
+            session = ChatSession(
+                id=session_id,
+                messages=[
+                    {"role": "system", "content": self.system_prompt}
+                ],
+            )
+
+        session.messages.append(
+            {"role": "user", "content": user_message}
+        )
+
+        ctx = AgentContext(
+            user=user,
+            tenant_id=tenant_id,
+            session_id=session_id,
+            metadata=metadata or {},
+        )
+
+        total_tool_calls = 0
+        content: str | None = None
+        error: str | None = None
+        model: str = ""
+        round_num = 0
+
+        for round_num in range(self.max_rounds):
+            try:
+                result = await self.completion.complete(
+                    messages=session.messages,
+                    tools=self.toolkit.tool_schemas,
+                    tool_choice="auto",
+                )
+            except Exception as exc:
+                logger.exception(
+                    "Completion backend failed in session %s",
+                    session_id,
+                )
+                error = f"LLM call failed: {exc}"
+                break
+
+            # Track model if available
+            if hasattr(result, "model") and result.model:
+                model = result.model
+
+            if not result.has_tool_calls:
+                content = result.content
+                session.messages.append(
+                    {"role": "assistant", "content": content}
+                )
+                break
+
+            # Build assistant message with tool calls
+            assistant_msg = _build_assistant_msg(result)
+            session.messages.append(assistant_msg)
+
+            # Execute each tool call
+            for tc in result.tool_calls:
+                total_tool_calls += 1
+                tool_result = await self._execute_tool(
+                    tc, ctx
+                )
+                tool_msg = _build_tool_result_msg(
+                    tc.id, tc.name, tool_result
+                )
+                session.messages.append(tool_msg)
+        else:
+            error = (
+                f"Max tool rounds ({self.max_rounds}) exceeded"
+            )
+            logger.warning(
+                "Max rounds (%d) reached for session %s",
+                self.max_rounds,
+                session_id,
+            )
+
+        await self.session_backend.save(session)
+
+        return AgentResponse(
+            content=content,
+            rounds=round_num + 1,
+            tool_calls_made=total_tool_calls,
+            error=error,
+            model=model,
+        )
+
+    async def _execute_tool(
+        self,
+        tool_call: Any,
+        ctx: AgentContext,
+    ) -> ToolResult:
+        """Execute a single tool call with error handling."""
+        try:
+            return await self.toolkit.execute(
+                tool_name=tool_call.name,
+                arguments=tool_call.arguments,
+                ctx=ctx,
+            )
+        except Exception as exc:
+            logger.exception(
+                "Tool %s failed: %s", tool_call.name, exc
+            )
+            return ToolResult(
+                success=False,
+                data=None,
+                error=f"Tool execution failed: {exc}",
+            )
+
+
+def _build_assistant_msg(result: Any) -> dict[str, Any]:
+    """Build assistant message dict from completion result."""
+    msg: dict[str, Any] = {
+        "role": "assistant",
+        "content": result.content,
+    }
+    if result.tool_calls:
+        msg["tool_calls"] = [
+            {
+                "id": tc.id,
+                "type": "function",
+                "function": {
+                    "name": tc.name,
+                    "arguments": json.dumps(tc.arguments),
+                },
+            }
+            for tc in result.tool_calls
+        ]
+    return msg
+
+
+def _build_tool_result_msg(
+    tool_call_id: str,
+    tool_name: str,
+    result: ToolResult,
+) -> dict[str, Any]:
+    """Build tool result message dict for the LLM."""
+    if result.success:
+        content = json.dumps(result.data, default=str)
+    else:
+        content = json.dumps({"error": result.error})
+
+    return {
+        "role": "tool",
+        "tool_call_id": tool_call_id,
+        "name": tool_name,
+        "content": content,
+    }

iil_chat_agent-0.1.0/src/chat_agent/composite.py

@@ -0,0 +1,85 @@
+"""CompositeToolkit — merges multiple DomainToolkits into one.
+
+Allows ChatAgent to use tools from multiple domains
+(e.g. TravelBeatToolkit + StoryToolkit) in a single session.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from .models import AgentContext, ToolResult
+from .toolkit import DomainToolkit
+
+logger = logging.getLogger(__name__)
+
+
+class CompositeToolkit(DomainToolkit):
+    """Merges multiple DomainToolkits into a single toolkit.
+
+    Tool dispatch is resolved at init time by mapping each
+    tool name to its owning toolkit. Collisions raise ValueError.
+
+    Usage::
+
+        composite = CompositeToolkit([
+            TravelBeatToolkit(),
+            StoryToolkit(),
+        ])
+        agent = ChatAgent(toolkit=composite, ...)
+    """
+
+    def __init__(
+        self, toolkits: list[DomainToolkit],
+    ) -> None:
+        self._toolkits = list(toolkits)
+        self._dispatch: dict[str, DomainToolkit] = {}
+
+        for tk in self._toolkits:
+            for schema in tk.tool_schemas:
+                tool_name = schema["function"]["name"]
+                if tool_name in self._dispatch:
+                    existing = self._dispatch[tool_name].name
+                    raise ValueError(
+                        f"Tool name collision: '{tool_name}' "
+                        f"exists in both '{existing}' and "
+                        f"'{tk.name}' toolkits."
+                    )
+                self._dispatch[tool_name] = tk
+
+        logger.info(
+            "CompositeToolkit created: %s (%d tools)",
+            self.name,
+            len(self._dispatch),
+        )
+
+    @property
+    def name(self) -> str:
+        return "+".join(tk.name for tk in self._toolkits)
+
+    @property
+    def tool_schemas(self) -> list[dict[str, Any]]:
+        schemas: list[dict[str, Any]] = []
+        for tk in self._toolkits:
+            schemas.extend(tk.tool_schemas)
+        return schemas
+
+    async def execute(
+        self,
+        tool_name: str,
+        arguments: dict[str, Any],
+        ctx: AgentContext,
+    ) -> ToolResult:
+        """Dispatch tool call to the owning toolkit."""
+        tk = self._dispatch.get(tool_name)
+        if not tk:
+            return ToolResult(
+                success=False,
+                data=None,
+                error=(
+                    f"Unknown tool: '{tool_name}'. "
+                    f"Available: {list(self._dispatch.keys())}"
+                ),
+            )
+        return await tk.execute(tool_name, arguments, ctx)

iil_chat_agent-0.1.0/src/chat_agent/models.py

@@ -0,0 +1,124 @@
+"""Pydantic models for the chat-agent package.
+
+Defines the core data structures for chat sessions, messages,
+tool results, and agent context.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ToolResult(BaseModel):
+    """Result of a single tool execution."""
+
+    model_config = ConfigDict(frozen=True)
+
+    success: bool = Field(description="Whether the tool call succeeded")
+    data: Any = Field(
+        default=None, description="Result data (dict, list, str)"
+    )
+    error: str | None = Field(
+        default=None, description="Error message if failed"
+    )
+
+
+class AgentContext(BaseModel):
+    """Context passed to every tool execution."""
+
+    model_config = ConfigDict(frozen=True)
+
+    user: Any = Field(
+        default=None, description="Authenticated user object"
+    )
+    tenant_id: str | None = Field(
+        default=None, description="Tenant ID for multi-tenancy"
+    )
+    session_id: str = Field(description="Current chat session ID")
+    metadata: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Additional context (e.g. project_id)",
+    )
+
+
+class ChatMessage(BaseModel):
+    """Single message in a chat session."""
+
+    model_config = ConfigDict(frozen=True)
+
+    role: str = Field(description="system, user, assistant, or tool")
+    content: str | None = Field(
+        default=None, description="Text content"
+    )
+    tool_calls: list[dict[str, Any]] = Field(
+        default_factory=list,
+        description="Tool calls (assistant role only)",
+    )
+    tool_call_id: str | None = Field(
+        default=None,
+        description="ID of the tool call this message responds to",
+    )
+    name: str | None = Field(
+        default=None, description="Tool name (tool role only)"
+    )
+
+    def to_api_dict(self) -> dict[str, Any]:
+        """Convert to API-compatible dict for LLM calls."""
+        d: dict[str, Any] = {"role": self.role}
+        if self.content is not None:
+            d["content"] = self.content
+        if self.tool_calls:
+            d["tool_calls"] = self.tool_calls
+        if self.tool_call_id is not None:
+            d["tool_call_id"] = self.tool_call_id
+        if self.name is not None:
+            d["name"] = self.name
+        return d
+
+
+class ChatSession(BaseModel):
+    """Persistent chat session with message history."""
+
+    id: str = Field(description="Unique session identifier")
+    messages: list[dict[str, Any]] = Field(
+        default_factory=list,
+        description="Message history (API-format dicts)",
+    )
+    metadata: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Session-level metadata",
+    )
+
+
+class AgentResponse(BaseModel):
+    """Response from ChatAgent.chat()."""
+
+    model_config = ConfigDict(frozen=True)
+
+    content: str | None = Field(
+        default=None,
+        description="Final text response from the agent",
+    )
+    rounds: int = Field(
+        default=1,
+        description="Number of LLM rounds used",
+    )
+    tool_calls_made: int = Field(
+        default=0,
+        description="Total tool calls executed",
+    )
+    error: str | None = Field(
+        default=None,
+        description="Error message if the agent failed",
+    )
+    model: str = Field(
+        default="",
+        description="LLM model used for the response",
+    )
+
+    @property
+    def success(self) -> bool:
+        """True if no error occurred."""
+        return self.error is None