tilo 0.1.0__tar.gz

tilo-0.1.0/.gitignore

@@ -0,0 +1,40 @@
+__pycache__/
+*.py[cod]
+*.pyo
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+
+node_modules/
+.next/
+
+.env
+.env.*
+!.env.example
+
+*.db
+*.db-shm
+*.db-wal
+
+evals/reports/*.json
+!evals/reports/.gitkeep
+
+.DS_Store
+Thumbs.db
+*.swp
+*.swo
+.logs/
+
+.codebuddy/
+
+# Demo recordings live in GitHub Releases, never the repo.
+# (See docs/demos/README.md for the canonical URLs.)
+*.mp4
+*.mov
+*.webm
+*.m4v

tilo-0.1.0/Dockerfile

@@ -0,0 +1,12 @@
+FROM python:3.12-slim
+
+WORKDIR /app
+
+COPY backend/pyproject.toml ./
+RUN pip install --no-cache-dir .
+
+COPY backend/tilo ./tilo
+COPY examples ./examples
+
+EXPOSE 8000
+CMD ["uvicorn", "tilo.main:app", "--host", "0.0.0.0", "--port", "8000"]

tilo-0.1.0/PKG-INFO

@@ -0,0 +1,24 @@
+Metadata-Version: 2.4
+Name: tilo
+Version: 0.1.0
+Summary: Tilo — AI-native SaaS agent framework with long-term memory, structured artifacts, and human confirmation.
+License: MIT
+Keywords: agent,ai,artifact,framework,memory,saas
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.11
+Requires-Dist: alembic>=1.13
+Requires-Dist: fastapi>=0.110
+Requires-Dist: httpx>=0.27
+Requires-Dist: psycopg[binary]>=3.1
+Requires-Dist: pydantic-settings>=2.2
+Requires-Dist: pydantic>=2.6
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: sqlalchemy>=2.0
+Requires-Dist: uvicorn[standard]>=0.27
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == 'test'

tilo-0.1.0/alembic/env.py

@@ -0,0 +1,62 @@
+"""Alembic environment configuration for Tilo Framework.
+
+The database URL is read from tilo.core.config (DATABASE_URL env var).
+All ORM models are imported here so Alembic can detect schema changes
+for `alembic revision --autogenerate`.
+"""
+from logging.config import fileConfig
+
+from sqlalchemy import engine_from_config, pool
+from alembic import context
+
+# Alembic Config provides access to alembic.ini values.
+config = context.config
+
+if config.config_file_name is not None:
+    fileConfig(config.config_file_name)
+
+# Import Base and register all models so target_metadata is complete.
+from tilo.core.database import Base  # noqa: E402
+import tilo.models.domain  # noqa: F401, E402 — registers all ORM tables
+
+target_metadata = Base.metadata
+
+
+def _get_url() -> str:
+    from tilo.core.config import get_settings
+    return get_settings().database_url
+
+
+def run_migrations_offline() -> None:
+    """Run migrations without a live DB connection (generates SQL script)."""
+    url = _get_url()
+    context.configure(
+        url=url,
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+        compare_type=True,
+    )
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def run_migrations_online() -> None:
+    """Run migrations against a live DB connection."""
+    cfg = dict(config.get_section(config.config_ini_section) or {})
+    cfg["sqlalchemy.url"] = _get_url()
+    connectable = engine_from_config(cfg, prefix="sqlalchemy.", poolclass=pool.NullPool)
+    with connectable.connect() as connection:
+        context.configure(
+            connection=connection,
+            target_metadata=target_metadata,
+            compare_type=True,
+        )
+        with context.begin_transaction():
+            context.run_migrations()
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()

tilo-0.1.0/alembic/versions/0001_initial_schema.py

@@ -0,0 +1,31 @@
+"""Initial schema baseline.
+
+Revision ID: 0001
+Revises:
+Create Date: 2026-06-04
+
+This migration is a **no-op baseline marker**.
+
+On fresh databases, `Base.metadata.create_all()` creates all tables
+before Alembic runs. The startup code then stamps this revision as
+applied so subsequent migrations are tracked correctly.
+
+On pre-Alembic databases (v0.1 installs), this migration records that
+the initial schema is already in place, and migration 0002 handles the
+additive v02 column changes.
+"""
+from alembic import op  # noqa: F401
+
+revision = "0001"
+down_revision = None
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    # Tables exist on all databases (either via create_all or pre-existing).
+    pass
+
+
+def downgrade() -> None:
+    pass

tilo-0.1.0/alembic/versions/0002_v02_columns.py

@@ -0,0 +1,99 @@
+"""Add v02 schema columns and surface_turns table.
+
+Revision ID: 0002
+Revises: 0001
+Create Date: 2026-06-04
+
+Converts the manual `ensure_v02_schema()` patches into tracked Alembic
+migrations. Each change is idempotent (checks before altering) so it is
+safe to run against databases that already applied `ensure_v02_schema`.
+
+Changes:
+  runs        → add session_id (VARCHAR, nullable)
+  memories    → add scope_type, scope_id, source_run_id, salience,
+                    status, structured_payload, supersedes_id,
+                    last_recalled_at, recall_count
+  surface_turns → create table if not present
+"""
+from __future__ import annotations
+
+import sqlalchemy as sa
+from alembic import op
+from sqlalchemy import inspect
+
+
+def _column_exists(table: str, column: str) -> bool:
+    bind = op.get_bind()
+    insp = inspect(bind)
+    return column in {col["name"] for col in insp.get_columns(table)}
+
+
+def _add_if_missing(table: str, column: str, col_type: sa.types.TypeEngine, server_default: str | None = None) -> None:
+    if not _column_exists(table, column):
+        op.add_column(table, sa.Column(column, col_type, server_default=server_default, nullable=True))
+
+
+revision = "0002"
+down_revision = "0001"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    bind = op.get_bind()
+    is_pg = bind.dialect.name == "postgresql"
+    datetime_type: sa.types.TypeEngine = sa.TIMESTAMP() if is_pg else sa.DateTime()
+
+    # -- runs ----------------------------------------------------------------
+    _add_if_missing("runs", "session_id", sa.String())
+
+    # -- memories ------------------------------------------------------------
+    _add_if_missing("memories", "scope_type", sa.String(), server_default="workspace")
+    _add_if_missing("memories", "scope_id", sa.String())
+    _add_if_missing("memories", "source_run_id", sa.String())
+    _add_if_missing("memories", "salience", sa.Float(), server_default="0.5")
+    _add_if_missing("memories", "status", sa.String(), server_default="candidate")
+    _add_if_missing("memories", "structured_payload", sa.JSON())
+    _add_if_missing("memories", "supersedes_id", sa.String())
+    _add_if_missing("memories", "last_recalled_at", datetime_type)
+    _add_if_missing("memories", "recall_count", sa.Integer(), server_default="0")
+
+    # Backfill status for rows that pre-date the column.
+    op.execute(
+        sa.text(
+            "UPDATE memories "
+            "SET status = CASE WHEN is_confirmed THEN 'confirmed' ELSE 'candidate' END "
+            "WHERE status IS NULL OR status = ''"
+        )
+    )
+    op.execute(sa.text("UPDATE memories SET salience = 0.5 WHERE salience IS NULL"))
+    op.execute(sa.text("UPDATE memories SET recall_count = 0 WHERE recall_count IS NULL"))
+    op.execute(
+        sa.text("UPDATE memories SET scope_type = 'workspace' WHERE scope_type IS NULL OR scope_type = ''")
+    )
+
+    # -- surface_turns -------------------------------------------------------
+    insp = inspect(bind)
+    if "surface_turns" not in insp.get_table_names():
+        op.create_table(
+            "surface_turns",
+            sa.Column("id", sa.String(), primary_key=True),
+            sa.Column("run_id", sa.String(), sa.ForeignKey("runs.id"), nullable=True, index=True),
+            sa.Column("session_id", sa.String(), sa.ForeignKey("conversation_sessions.id"), nullable=True, index=True),
+            sa.Column("workspace_id", sa.String(), nullable=True),
+            sa.Column("step_index", sa.Integer(), nullable=True),
+            sa.Column("intent", sa.String(), nullable=True),
+            sa.Column("spec_json", sa.JSON(), nullable=True),
+            sa.Column("budget_hint", sa.String(), nullable=True),
+            sa.Column("created_at", datetime_type, nullable=True),
+            sa.Column("updated_at", datetime_type, nullable=True),
+        )
+
+
+def downgrade() -> None:
+    # Additive column migrations are not reversible in production.
+    # Drop surface_turns only (safe — it is the newest table).
+    bind = op.get_bind()
+    insp = inspect(bind)
+    if "surface_turns" in insp.get_table_names():
+        op.drop_table("surface_turns")

tilo-0.1.0/alembic.ini

@@ -0,0 +1,43 @@
+# Alembic configuration for Tilo Framework.
+# The database URL is intentionally blank — it is injected at runtime
+# by alembic/env.py from tilo.core.config (respects DATABASE_URL env var).
+
+[alembic]
+script_location = alembic
+prepend_sys_path = .
+file_template = %%(rev)s_%%(slug)s
+truncate_slug_length = 40
+
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARN
+handlers = console
+qualname =
+
+[logger_sqlalchemy]
+level = WARN
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers =
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s
+datefmt = %H:%M:%S

tilo-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "tilo"
+version = "0.1.0"
+description = "Tilo — AI-native SaaS agent framework with long-term memory, structured artifacts, and human confirmation."
+requires-python = ">=3.11"
+license = { text = "MIT" }
+keywords = ["ai", "agent", "framework", "memory", "artifact", "saas"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Framework :: FastAPI",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Libraries :: Application Frameworks",
+]
+dependencies = [
+  "fastapi>=0.110",
+  "uvicorn[standard]>=0.27",
+  "sqlalchemy>=2.0",
+  "alembic>=1.13",
+  "pydantic>=2.6",
+  "pydantic-settings>=2.2",
+  "psycopg[binary]>=3.1",
+  "httpx>=0.27",
+  "PyYAML>=6.0",
+]
+
+[project.optional-dependencies]
+test = ["pytest>=8.0"]
+
+[project.scripts]
+# `pip install tilo` gives you:
+#   tilo serve     — start the API server
+#   tilo init      — scaffold a new Tilo project
+tilo = "tilo.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["tilo"]
+
+[tool.pytest.ini_options]
+pythonpath = ["."]

tilo-0.1.0/tests/helpers.py

@@ -0,0 +1,92 @@
+import os
+import json
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+import pytest
+
+db_path = Path(tempfile.gettempdir()) / "tilo_smoke_test.db"
+if db_path.exists():
+    db_path.unlink()
+
+os.environ["DATABASE_URL"] = f"sqlite:///{db_path}"
+os.environ["LLM_ENABLED"] = "false"
+os.environ["LLM_PROVIDER"] = "openai"
+os.environ["LLM_BASE_URL"] = ""
+os.environ["OPENAI_API_KEY"] = ""
+
+from fastapi.testclient import TestClient  # noqa: E402
+
+from tilo.core.config import Settings  # noqa: E402
+from tilo.core.database import SessionLocal  # noqa: E402
+from tilo.main import app  # noqa: E402
+from tilo.models import Artifact, Confirmation, ContextReflection, ConversationSession, ConversationTurn, Memory, Run, Task, Tool, TraceStep, UIInteractionEvent  # noqa: E402
+from tilo.services.agent_context import AgentContextBuilder  # noqa: E402
+from tilo.services.agent_runtime.run_manager import RunManager  # noqa: E402
+from tilo.services.agent_runtime.prompt_builder import PromptBuilder  # noqa: E402
+from tilo.services.agent_runtime.state_machine import InvalidStateTransition, RunStateMachine  # noqa: E402
+from tilo.services.artifact.generator import ArtifactGenerator  # noqa: E402
+from tilo.services.artifact.spec import ArtifactSpecBuilder  # noqa: E402
+from tilo.services.channels.telegram.adapter import TelegramAdapter  # noqa: E402
+from tilo.services.channels.telegram.types import parse_telegram_callback_data  # noqa: E402
+from tilo.services.artifact.contract_llm import ContractReviewLLMGenerator  # noqa: E402
+from tilo.services.models.client import ModelClient  # noqa: E402
+from tilo.services.models.errors import ModelDisabledError, ModelInvalidJSONError  # noqa: E402
+from tilo.services.demo import load_problematic_ai_service_agreement  # noqa: E402
+from tilo.services.apps.loader import AgentAppLoader, get_app_loader  # noqa: E402
+from tilo.services.conversations.constants import ConversationChannel, ConversationTurnType  # noqa: E402
+from tilo.services.conversations.service import ConversationService  # noqa: E402
+from tilo.services.context_reflection import ContextReflectionService  # noqa: E402
+from tilo.services.interaction_policy.schemas import InteractionContext, InteractionDecisionType  # noqa: E402
+from tilo.services.interaction_policy.service import InteractionPolicyService  # noqa: E402
+from tilo.schemas import RichSurfaceLink  # noqa: E402
+from tilo.schemas.artifact import CORE_BLOCK_TYPES, PRIMITIVE_BLOCK_TYPES, ArtifactSpecV1  # noqa: E402
+from tilo.services.surfaces.constants import RichSurfaceSource, RichSurfaceTargetType  # noqa: E402
+from tilo.services.surfaces.rich_links import create_rich_surface_link  # noqa: E402
+from tilo.services.trace.recorder import TraceRecorder  # noqa: E402
+
+
+def create_action_artifact(
+    *,
+    workspace_id: str,
+    actions: list[dict] | None = None,
+    blocks: list[dict] | None = None,
+    run_id: str | None = None,
+) -> str:
+    with SessionLocal() as db:
+        artifact = Artifact(
+            workspace_id=workspace_id,
+            run_id=run_id,
+            title="Action Runtime Artifact",
+            type="contract_review",
+            schema_json={
+                "version": "artifact_spec.v1",
+                "artifact_type": "contract_review",
+                "title": "Action Runtime Artifact",
+                "status": "ready",
+                "blocks": blocks
+                or [
+                    {
+                        "id": "summary",
+                        "type": "approval_card",
+                        "data": {"title": "Approve"},
+                        "actions": [
+                            {
+                                "id": "approve_block",
+                                "label": "Approve block",
+                                "action_type": "approve",
+                                "confirmation_required": False,
+                            }
+                        ],
+                    }
+                ],
+                "actions": actions or [],
+                "run_id": run_id,
+            },
+        )
+        db.add(artifact)
+        db.commit()
+        db.refresh(artifact)
+        return artifact.id

tilo-0.1.0/tests/test_aip_generator.py

@@ -0,0 +1,64 @@
+"""Tests for the AIP spec generator and skill hint system."""
+from helpers import *  # noqa: F401,F403
+
+from tilo.services.artifact.aip_generator import (
+    AIPSpecGenerator,
+    ArtifactTypeDetector,
+    _detect_skill_hint,
+    _DEMO_SKILL_HINTS,
+)
+
+
+def test_skill_hint_detection_contract() -> None:
+    hint = _detect_skill_hint("Review this contract for risky clauses")
+    assert hint == _DEMO_SKILL_HINTS["contract_review"]
+
+
+def test_skill_hint_detection_sales() -> None:
+    hint = _detect_skill_hint("Follow up with my top customers")
+    assert hint == _DEMO_SKILL_HINTS["sales_dashboard"]
+
+
+def test_skill_hint_detection_code_review() -> None:
+    hint = _detect_skill_hint("Review this pull request from the auth refactor branch")
+    assert hint == _DEMO_SKILL_HINTS["code_review"]
+
+
+def test_skill_hint_detection_generic() -> None:
+    hint = _detect_skill_hint("Write me a poem about cats")
+    assert hint is None
+
+
+def test_artifact_type_detector() -> None:
+    d = ArtifactTypeDetector()
+    assert d.detect("review this contract") == "contract_review"
+    assert d.detect("follow up with sales leads") == "dashboard"
+    assert d.detect("review this pull request") == "code_review"
+    assert d.detect("help me write a report") == "document"
+    assert d.detect("审查这份合同") == "contract_review"
+    assert d.detect("代码评审一下这个 PR") == "code_review"
+
+
+def test_aip_deterministic_fallback() -> None:
+    """AIPSpecGenerator without a model client should produce a valid deterministic spec."""
+    task = Task(id="t1", workspace_id="ws", title="Test", input_message="Hello world")
+    run = Run(id="r1", task_id="t1")
+    gen = AIPSpecGenerator(client=None)
+    result = gen.generate(task, run, [], [])
+    assert result["version"] == "tilo/aip/v1"
+    assert result["_generation_mode"] == "deterministic"
+    assert len(result["blocks"]) >= 1
+    spec = ArtifactSpecV1.model_validate(result)
+    assert spec.title
+
+
+def test_aip_deterministic_fallback_chinese() -> None:
+    """Even with Chinese input, the demo fallback now returns English titles
+    so the Canvas demo stays consistent. The hint detector still triggers
+    contract scenario via Chinese keywords."""
+    task = Task(id="t2", workspace_id="ws", title="Test", input_message="审查这份合同")
+    run = Run(id="r2", task_id="t2")
+    gen = AIPSpecGenerator(client=None)
+    result = gen.generate(task, run, [], [])
+    assert result["title"] == "Contract Review"
+    assert len(result["blocks"]) >= 5  # Rich multi-block output