tilo 0.1.0__py3-none-any.whl

tilo/__init__.py

@@ -0,0 +1 @@
+

tilo/adapters/__init__.py

@@ -0,0 +1,5 @@
+"""Tilo Protocol Adapters — bridges between external protocols and Tilo AIP.
+
+Each adapter converts protocol-specific output into Tilo ArtifactBlocks,
+enabling zero-code integration with the Tilo Canvas.
+"""

tilo/adapters/a2a.py

@@ -0,0 +1,29 @@
+"""A2A (Agent-to-Agent) → Tilo AIP adapter (stub).
+
+Converts Google A2A protocol task results into Tilo AIP specs.
+
+Status: Interface only. Implementation planned for future milestone.
+"""
+
+from typing import Any
+
+
+def a2a_task_to_spec(task_result: dict[str, Any]) -> dict[str, Any]:
+    """Convert an A2A task result to a Tilo AIP spec. Stub."""
+    return {
+        "version": "tilo/aip/v1",
+        "title": task_result.get("name", "A2A Task Result"),
+        "status": "ready",
+        "blocks": [
+            {
+                "id": "a2a_result",
+                "type": "markdown",
+                "props": {"content": str(task_result.get("output", "No output."))},
+            },
+        ],
+        "views": [],
+        "actions": [],
+        "provenance": [],
+        "memory_refs": [],
+        "follow_ups": [],
+    }

tilo/adapters/acp.py

@@ -0,0 +1,29 @@
+"""ACP (Agent Communication Protocol) → Tilo AIP adapter (stub).
+
+Converts ACP messages into Tilo AIP specs.
+
+Status: Interface only. Implementation planned for future milestone.
+"""
+
+from typing import Any
+
+
+def acp_message_to_spec(message: dict[str, Any]) -> dict[str, Any]:
+    """Convert an ACP message to a Tilo AIP spec. Stub."""
+    return {
+        "version": "tilo/aip/v1",
+        "title": message.get("subject", "ACP Message"),
+        "status": "ready",
+        "blocks": [
+            {
+                "id": "acp_content",
+                "type": "markdown",
+                "props": {"content": str(message.get("body", "No content."))},
+            },
+        ],
+        "views": [],
+        "actions": [],
+        "provenance": [],
+        "memory_refs": [],
+        "follow_ups": [],
+    }

tilo/adapters/langchain.py

@@ -0,0 +1,347 @@
+"""LangChain → Tilo AIP adapter.
+
+Provides a callback handler that captures LangChain chain output
+and converts it into a Tilo AIP spec.
+
+Usage (callback — integrates with any LangChain chain):
+    from tilo.adapters.langchain import TiloCallbackHandler
+
+    handler = TiloCallbackHandler(run_id="my-tilo-run")
+    chain.invoke(input, config={"callbacks": [handler]})
+    spec = handler.to_spec()            # → Tilo AIP v1 dict
+
+Usage (direct conversion — convert a chain output dict):
+    from tilo.adapters.langchain import langchain_result_to_spec
+
+    spec = langchain_result_to_spec("MyChain", outputs)
+
+Design notes:
+- No hard dependency on langchain at import time (duck-typed interface).
+  The handler works with any object that calls these methods.
+- Structured output (dict / list-of-dicts) maps to metric / table blocks.
+- Tool calls map to tool_preview blocks with success / error status.
+- on_chain_end is a fallback: if finer-grained callbacks already captured
+  output, it is skipped to avoid duplication.
+"""
+
+from __future__ import annotations
+
+import json
+import uuid
+from typing import Any
+
+
+# --------------------------------------------------------------------------- #
+# Internal helpers                                                             #
+# --------------------------------------------------------------------------- #
+
+def _new_id(prefix: str = "lc") -> str:
+    return f"{prefix}_{uuid.uuid4().hex[:8]}"
+
+
+def _text_to_block(text: str, block_id: str | None = None) -> dict[str, Any]:
+    return {
+        "id": block_id or _new_id("lc_text"),
+        "type": "markdown",
+        "title": None,
+        "props": {"content": text.strip()},
+    }
+
+
+def _tool_result_to_block(
+    tool_name: str,
+    output: str,
+    block_id: str | None = None,
+    *,
+    is_error: bool = False,
+) -> dict[str, Any]:
+    return {
+        "id": block_id or _new_id("lc_tool"),
+        "type": "tool_preview",
+        "title": tool_name,
+        "props": {
+            "tool_name": tool_name,
+            "status": "error" if is_error else "success",
+            "output": str(output)[:2000],
+        },
+    }
+
+
+def _structured_output_to_blocks(
+    data: Any,
+    block_id_prefix: str = "lc_struct",
+) -> list[dict[str, Any]]:
+    """Convert a structured value (dict / list) to appropriate block types.
+
+    - Flat dict with ≤8 numeric/short-string values → metric blocks.
+    - List of dicts → table block.
+    - Anything else → markdown with JSON pretty-print.
+    """
+    if isinstance(data, dict):
+        is_metrics = (
+            len(data) <= 8
+            and all(
+                isinstance(v, (int, float))
+                or (isinstance(v, str) and len(v) < 40)
+                for v in data.values()
+            )
+        )
+        if is_metrics:
+            return [
+                {
+                    "id": f"{block_id_prefix}_{i}",
+                    "type": "metric",
+                    "title": key.replace("_", " ").title(),
+                    "props": {
+                        "label": key.replace("_", " ").title(),
+                        "value": str(value),
+                    },
+                }
+                for i, (key, value) in enumerate(data.items())
+            ]
+        return [_text_to_block(
+            f"```json\n{json.dumps(data, indent=2, ensure_ascii=False)}\n```",
+            f"{block_id_prefix}_json",
+        )]
+
+    if isinstance(data, list) and data and isinstance(data[0], dict):
+        columns = list(data[0].keys())
+        rows = [[str(row.get(col, "")) for col in columns] for row in data]
+        return [{
+            "id": f"{block_id_prefix}_table",
+            "type": "table",
+            "title": None,
+            "props": {
+                "columns": [{"key": c, "label": c.replace("_", " ").title()} for c in columns],
+                "rows": rows,
+            },
+        }]
+
+    return [_text_to_block(
+        json.dumps(data, indent=2, ensure_ascii=False),
+        f"{block_id_prefix}_fallback",
+    )]
+
+
+def _parse_message_content(content: str | list[Any]) -> str:
+    """Extract plain text from a LangChain message content field.
+
+    Content can be a plain string or a list of typed dicts
+    (e.g. [{"type": "text", "text": "…"}, {"type": "image_url", …}]).
+    """
+    if isinstance(content, str):
+        return content
+    parts: list[str] = []
+    for item in content:
+        if isinstance(item, dict):
+            if item.get("type") == "text":
+                parts.append(item.get("text", ""))
+            elif item.get("type") == "image_url":
+                parts.append("[image]")
+        elif isinstance(item, str):
+            parts.append(item)
+    return "\n".join(parts)
+
+
+def _spec(
+    blocks: list[dict[str, Any]],
+    title: str,
+    run_id: str | None,
+    provenance_id: str,
+) -> dict[str, Any]:
+    effective_blocks = blocks or [_text_to_block("No output captured.", "lc_empty")]
+    result: dict[str, Any] = {
+        "version": "tilo/aip/v1",
+        "title": title,
+        "status": "ready",
+        "blocks": effective_blocks,
+        "views": [
+            {
+                "id": "result",
+                "label": "Result",
+                "block_ids": [b["id"] for b in effective_blocks],
+            }
+        ],
+        "actions": [],
+        "provenance": [{"type": "langchain_chain", "id": provenance_id}],
+        "memory_refs": [],
+        "follow_ups": [],
+    }
+    if run_id:
+        result["run_id"] = run_id
+    return result
+
+
+# --------------------------------------------------------------------------- #
+# Public: direct conversion                                                    #
+# --------------------------------------------------------------------------- #
+
+def langchain_result_to_spec(
+    chain_name: str,
+    outputs: dict[str, Any],
+    *,
+    run_id: str | None = None,
+) -> dict[str, Any]:
+    """Convert a LangChain chain output dict directly into a Tilo AIP v1 spec.
+
+    Args:
+        chain_name: Name of the chain (used as spec title and provenance).
+        outputs:    The dict returned by ``chain.invoke()``.
+        run_id:     Optional Tilo run_id to embed in the spec.
+
+    Returns:
+        A Tilo AIP v1 spec dict ready for use with ArtifactSpecV1.model_validate().
+    """
+    blocks: list[dict[str, Any]] = []
+    for key, value in outputs.items():
+        if isinstance(value, str):
+            if value.strip():
+                blocks.append(_text_to_block(value, f"lc_out_{key}"))
+        elif isinstance(value, (dict, list)):
+            blocks.extend(_structured_output_to_blocks(value, f"lc_out_{key}"))
+        else:
+            blocks.append(_text_to_block(str(value), f"lc_out_{key}"))
+
+    return _spec(blocks, chain_name, run_id, chain_name)
+
+
+# --------------------------------------------------------------------------- #
+# Public: callback handler                                                     #
+# --------------------------------------------------------------------------- #
+
+class TiloCallbackHandler:
+    """LangChain callback handler that accumulates output as Tilo AIP blocks.
+
+    Duck-typed — no langchain import required. Compatible with:
+    - LangChain v0.1+ (``BaseCallbackHandler`` interface)
+    - LangGraph nodes that emit callbacks
+    - Any object that calls these methods
+
+    Example:
+        handler = TiloCallbackHandler(run_id="tilo-run-123")
+        chain.invoke(input, config={"callbacks": [handler]})
+        spec = handler.to_spec()
+        validated = ArtifactSpecV1.model_validate(spec)
+    """
+
+    def __init__(
+        self,
+        run_id: str | None = None,
+        title: str = "LangChain Result",
+    ) -> None:
+        self.run_id = run_id
+        self.title = title
+        self.blocks: list[dict[str, Any]] = []
+        self._tool_names: dict[str, str] = {}  # callback run_id → tool name
+
+    # ------------------------------------------------------------------ #
+    # LLM callbacks                                                        #
+    # ------------------------------------------------------------------ #
+
+    def on_chat_model_start(
+        self,
+        serialized: dict[str, Any],
+        messages: list[Any],
+        **kwargs: Any,
+    ) -> None:
+        """No-op — output captured in on_llm_end."""
+
+    def on_llm_end(self, response: Any, **kwargs: Any) -> None:
+        """Capture LLM text output as a markdown block."""
+        try:
+            generation = response.generations[0][0]
+            text: str = getattr(generation, "text", "") or ""
+            if not text and hasattr(generation, "message"):
+                text = _parse_message_content(
+                    getattr(generation.message, "content", "")
+                )
+            if text.strip():
+                self.blocks.append(_text_to_block(text, _new_id("lc_llm")))
+        except (AttributeError, IndexError):
+            pass
+
+    # ------------------------------------------------------------------ #
+    # Tool callbacks                                                       #
+    # ------------------------------------------------------------------ #
+
+    def on_tool_start(
+        self,
+        serialized: dict[str, Any],
+        input_str: str,
+        **kwargs: Any,
+    ) -> None:
+        """Record tool name so on_tool_end can label the block."""
+        cb_run_id = str(kwargs.get("run_id", ""))
+        tool_name = serialized.get("name", "tool")
+        if cb_run_id:
+            self._tool_names[cb_run_id] = tool_name
+
+    def on_tool_end(self, output: Any, **kwargs: Any) -> None:
+        """Capture tool output as a tool_preview block."""
+        cb_run_id = str(kwargs.get("run_id", ""))
+        tool_name = self._tool_names.pop(cb_run_id, "tool")
+        self.blocks.append(
+            _tool_result_to_block(tool_name, str(output), _new_id("lc_tool"))
+        )
+
+    def on_tool_error(self, error: Exception, **kwargs: Any) -> None:
+        """Capture tool error as a tool_preview block with error status."""
+        cb_run_id = str(kwargs.get("run_id", ""))
+        tool_name = self._tool_names.pop(cb_run_id, "tool")
+        self.blocks.append(
+            _tool_result_to_block(
+                tool_name, str(error), _new_id("lc_tool_err"), is_error=True
+            )
+        )
+
+    # ------------------------------------------------------------------ #
+    # Agent callbacks                                                      #
+    # ------------------------------------------------------------------ #
+
+    def on_agent_finish(self, finish: Any, **kwargs: Any) -> None:
+        """Capture the final agent answer, avoiding duplicates from on_llm_end."""
+        try:
+            return_values: dict[str, Any] = getattr(finish, "return_values", {})
+            output = return_values.get("output", "") if isinstance(return_values, dict) else ""
+            if not (output and isinstance(output, str)):
+                return
+            already = any(
+                b.get("props", {}).get("content", "").strip() == output.strip()
+                for b in self.blocks
+                if b.get("type") == "markdown"
+            )
+            if not already:
+                self.blocks.append(_text_to_block(output, _new_id("lc_agent")))
+        except AttributeError:
+            pass
+
+    # ------------------------------------------------------------------ #
+    # Chain callbacks                                                      #
+    # ------------------------------------------------------------------ #
+
+    def on_chain_end(self, outputs: dict[str, Any], **kwargs: Any) -> None:
+        """Fallback: capture structured chain output if no blocks exist yet."""
+        if self.blocks:
+            return  # finer-grained callbacks already captured content
+        if not isinstance(outputs, dict):
+            return
+        for key, value in outputs.items():
+            if isinstance(value, str) and value.strip():
+                self.blocks.append(_text_to_block(value, f"lc_chain_{key}"))
+            elif isinstance(value, (dict, list)):
+                self.blocks.extend(
+                    _structured_output_to_blocks(value, f"lc_chain_{key}")
+                )
+
+    # ------------------------------------------------------------------ #
+    # Output                                                               #
+    # ------------------------------------------------------------------ #
+
+    def to_spec(self) -> dict[str, Any]:
+        """Assemble all captured blocks into a Tilo AIP v1 spec dict."""
+        return _spec(self.blocks, self.title, self.run_id, self.title)
+
+    def reset(self) -> None:
+        """Clear all captured state. Allows reuse across multiple chain runs."""
+        self.blocks.clear()
+        self._tool_names.clear()

tilo/adapters/mcp.py

@@ -0,0 +1,125 @@
+"""MCP → Tilo AIP adapter.
+
+Converts MCP (Model Context Protocol) tool results into Tilo ArtifactBlocks.
+
+Usage:
+    from tilo.adapters.mcp import mcp_content_to_blocks
+
+    blocks = mcp_content_to_blocks(mcp_result.content)
+
+Mapping:
+    TextContent   → markdown block
+    ImageContent  → image block
+    EmbeddedResource → card block with metadata
+"""
+
+from typing import Any
+
+
+def mcp_content_to_blocks(content: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """Convert a list of MCP Content items to Tilo ArtifactBlocks.
+
+    MCP Content follows the spec at https://modelcontextprotocol.io
+    Each item has a "type" field: "text", "image", or "resource".
+
+    Args:
+        content: List of MCP Content dicts, each with at minimum a "type" field.
+
+    Returns:
+        List of Tilo ArtifactBlock dicts ready for inclusion in a spec.
+    """
+    blocks: list[dict[str, Any]] = []
+    for i, item in enumerate(content):
+        content_type = item.get("type", "text")
+        block_id = f"mcp_{i}"
+
+        if content_type == "text":
+            blocks.append({
+                "id": block_id,
+                "type": "markdown",
+                "title": None,
+                "props": {
+                    "content": item.get("text", ""),
+                },
+            })
+
+        elif content_type == "image":
+            blocks.append({
+                "id": block_id,
+                "type": "image",
+                "title": None,
+                "props": {
+                    "src": item.get("data", ""),
+                    "alt": item.get("mimeType", "image"),
+                    "mime_type": item.get("mimeType", "image/png"),
+                    "encoding": "base64",
+                },
+            })
+
+        elif content_type == "resource":
+            resource = item.get("resource", {})
+            blocks.append({
+                "id": block_id,
+                "type": "card",
+                "title": resource.get("name") or resource.get("uri", "Resource"),
+                "props": {
+                    "title": resource.get("name") or "Embedded Resource",
+                    "content": resource.get("text", ""),
+                    "uri": resource.get("uri"),
+                    "mime_type": resource.get("mimeType"),
+                },
+            })
+
+        else:
+            # Unknown MCP content type → generic block
+            blocks.append({
+                "id": block_id,
+                "type": "card",
+                "title": f"MCP {content_type}",
+                "props": item,
+            })
+
+    return blocks
+
+
+def mcp_tool_result_to_spec(
+    tool_name: str,
+    content: list[dict[str, Any]],
+    *,
+    is_error: bool = False,
+) -> dict[str, Any]:
+    """Convert a complete MCP tool result into a minimal Tilo AIP spec.
+
+    This creates a ready-to-render spec with a single "Result" view.
+    """
+    blocks = mcp_content_to_blocks(content)
+
+    if is_error:
+        blocks.insert(0, {
+            "id": "mcp_error",
+            "type": "card",
+            "title": "Tool Error",
+            "props": {
+                "title": f"Error from {tool_name}",
+                "content": "The tool returned an error. See details below.",
+                "severity": "high",
+            },
+        })
+
+    return {
+        "version": "tilo/aip/v1",
+        "title": f"{tool_name} Result",
+        "status": "ready",
+        "blocks": blocks,
+        "views": [
+            {
+                "id": "result",
+                "label": "Result",
+                "block_ids": [b["id"] for b in blocks],
+            },
+        ],
+        "actions": [],
+        "provenance": [],
+        "memory_refs": [],
+        "follow_ups": [],
+    }

tilo/api/__init__.py

@@ -0,0 +1 @@
+

tilo/api/deps.py

@@ -0,0 +1,20 @@
+from typing import Any, TypeVar
+
+from fastapi import HTTPException
+from sqlalchemy.orm import Session
+
+ModelT = TypeVar("ModelT")
+
+
+def get_one(db: Session, model: type[ModelT], item_id: str) -> ModelT:
+    item = db.get(model, item_id)
+    if not item:
+        raise HTTPException(status_code=404, detail=f"{model.__name__} not found")
+    return item
+
+
+def apply_update(item: Any, patch: dict[str, Any]) -> Any:
+    for key, value in patch.items():
+        if hasattr(item, key) and key not in {"id", "created_at"}:
+            setattr(item, key, value)
+    return item

tilo/api/routes/__init__.py

@@ -0,0 +1,22 @@
+from tilo.api.routes import agents, apps, artifacts, channels, confirmations, conversations, demo, feedback, interactions, memories, messages, projects, runs, skills, system, tasks, tools, workspaces
+
+routers = [
+    system.router,
+    apps.router,
+    workspaces.router,
+    projects.router,
+    agents.router,
+    tasks.router,
+    runs.router,
+    messages.router,
+    conversations.router,
+    channels.router,
+    interactions.router,
+    feedback.router,
+    memories.router,
+    artifacts.router,
+    confirmations.router,
+    demo.router,
+    skills.router,
+    tools.router,
+]

tilo/api/routes/agents.py

@@ -0,0 +1,40 @@
+from collections.abc import Sequence
+from typing import Any
+
+from fastapi import APIRouter, Depends
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from tilo.api.deps import apply_update, get_one
+from tilo.core.database import get_db
+from tilo.models import Agent
+from tilo.schemas import AgentCreate, AgentRead
+
+router = APIRouter(prefix="/api/agents", tags=["agents"])
+
+
+@router.get("", response_model=list[AgentRead])
+def list_agents(workspace_id: str, db: Session = Depends(get_db)) -> Sequence[Agent]:
+    return db.scalars(select(Agent).where(Agent.workspace_id == workspace_id).order_by(Agent.created_at)).all()
+
+
+@router.post("", response_model=AgentRead)
+def create_agent(payload: AgentCreate, db: Session = Depends(get_db)) -> Agent:
+    item = Agent(**payload.model_dump())
+    db.add(item)
+    db.commit()
+    db.refresh(item)
+    return item
+
+
+@router.get("/{item_id}", response_model=AgentRead)
+def read_agent(item_id: str, db: Session = Depends(get_db)) -> Agent:
+    return get_one(db, Agent, item_id)
+
+
+@router.patch("/{item_id}", response_model=AgentRead)
+def update_agent(item_id: str, payload: dict[str, Any], db: Session = Depends(get_db)) -> Agent:
+    item = apply_update(get_one(db, Agent, item_id), payload)
+    db.commit()
+    db.refresh(item)
+    return item

tilo/api/routes/apps.py

@@ -0,0 +1,55 @@
+from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel
+from sqlalchemy.orm import Session
+
+from tilo.core.database import get_db
+from tilo.services.agent_context import AgentContextBuilder
+from tilo.services.apps import AgentAppManifest
+from tilo.services.apps.loader import get_app_loader
+from tilo.services.interaction_policy.schemas import InteractionContext, InteractionDecision
+from tilo.services.interaction_policy.service import InteractionPolicyService
+
+router = APIRouter(prefix="/api/apps", tags=["apps"])
+
+
+class AgentContextBuildRequest(BaseModel):
+    workspace_id: str
+    project_id: str | None = None
+    artifact_id: str | None = None
+    policy_context: InteractionContext | None = None
+
+
+@router.get("", response_model=list[AgentAppManifest])
+def list_apps() -> list[AgentAppManifest]:
+    return get_app_loader().list_apps()
+
+
+@router.get("/{app_id}", response_model=AgentAppManifest)
+def read_app(app_id: str) -> AgentAppManifest:
+    try:
+        return get_app_loader().load_manifest(app_id)
+    except (FileNotFoundError, ValueError) as exc:
+        raise HTTPException(status_code=404, detail=str(exc)) from exc
+
+
+@router.post("/{app_id}/interaction-policy/evaluate", response_model=InteractionDecision)
+def evaluate_app_interaction_policy(app_id: str, context: InteractionContext) -> InteractionDecision:
+    try:
+        return InteractionPolicyService().evaluate_for_app(app_id, context)
+    except (FileNotFoundError, ValueError) as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+
+@router.post("/{app_id}/agent-context")
+def build_agent_context(app_id: str, payload: AgentContextBuildRequest, db: Session = Depends(get_db)) -> dict:
+    try:
+        get_app_loader().load_manifest(app_id)
+        return AgentContextBuilder(db).build(
+            app_id=app_id,
+            workspace_id=payload.workspace_id,
+            project_id=payload.project_id,
+            artifact_id=payload.artifact_id,
+            policy_context=payload.policy_context,
+        )
+    except (FileNotFoundError, ValueError) as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc