planar 0.8.0__py3-none-any.whl → 0.9.1__py3-none-any.whl

planar/db/db.py

@@ -20,7 +20,10 @@ from sqlmodel.ext.asyncio.session import AsyncSession
 
 import planar
 from planar.logging import get_logger
-from planar.modeling.orm.planar_base_entity import PLANAR_APPLICATION_METADATA
+from planar.modeling.orm.planar_base_entity import (
+    PLANAR_APPLICATION_METADATA,
+    PLANAR_ENTITY_SCHEMA,
+)
 from planar.utils import P, R, T, U, exponential_backoff_with_jitter
 
 
@@ -170,9 +173,12 @@ class DatabaseManager:
     def __init__(
         self,
         db_url: str | URL,
+        *,
+        entity_schema: str = PLANAR_ENTITY_SCHEMA,
     ):
         self.db_url = make_url(db_url) if isinstance(db_url, str) else db_url
         self.engine: AsyncEngine | None = None
+        self.entity_schema = entity_schema
 
     def _create_sqlite_engine(self, url: URL) -> AsyncEngine:
         # in practice this high timeout is only use
@@ -189,9 +195,14 @@ class DatabaseManager:
                 # even though it is the default value.
                 autocommit=LEGACY_TRANSACTION_CONTROL,
             ),
-            # SQLite doesn't support schemas, so we need to translate the planar schema
-            # name to None.
-            execution_options={"schema_translate_map": {"planar": None}},
+            # SQLite doesn't support schemas, so we need to translate the planar and user
+            # schema names to None.
+            execution_options={
+                "schema_translate_map": {
+                    "planar": None,
+                    PLANAR_ENTITY_SCHEMA: None,
+                }
+            },
         )
 
         def do_begin(conn: Connection):
@@ -202,7 +213,12 @@ class DatabaseManager:
         return engine
 
     def _create_postgresql_engine(self, url: URL) -> AsyncEngine:
-        engine = create_async_engine(url)
+        # Map default (PLANAR_ENTITY_SCHEMA) schema to the configured entity schema for user tables.
+        # Leave the system table schema ('planar') unmapped so system tables are not overridden.
+        schema_map = {PLANAR_ENTITY_SCHEMA: self.entity_schema}
+        engine = create_async_engine(
+            url, execution_options={"schema_translate_map": schema_map}
+        )
 
         return engine
 
@@ -214,6 +230,12 @@ class DatabaseManager:
 
         db_backend = self.db_url.get_backend_name()
 
+        if self.entity_schema == PLANAR_SCHEMA:
+            logger.warning(
+                "entity_schema is set to 'planar'; mixing user and system tables in the same schema is discouraged",
+                entity_schema=self.entity_schema,
+            )
+
         match db_backend:
             case "sqlite":
                 logger.info(
@@ -293,27 +315,23 @@ class DatabaseManager:
             else:
                 # Ensure planar schema exists
                 await conn.execute(text(f"CREATE SCHEMA IF NOT EXISTS {PLANAR_SCHEMA}"))
+                # Ensure the configured entity schema exists
+                if self.entity_schema != PLANAR_SCHEMA:
+                    await conn.execute(
+                        text(f"CREATE SCHEMA IF NOT EXISTS {self.entity_schema}")
+                    )
 
-    async def migrate(self, use_alembic: bool):
+    async def migrate(self):
         """
         Runs database migrations.
         By default, uses SQLModel.metadata.create_all.
-        Set use_alembic=True to use Alembic (requires Alembic setup).
         """
         if not self.engine:
             raise RuntimeError("Database engine not initialized. Call connect() first.")
 
-        logger.info("starting database migration")
-        if use_alembic:
-            logger.info("using alembic for migrations")
-            await self._setup_database()
-            await self._run_system_migrations()
-            # For now user migrations are not supported, so we fall back to SQLModel.metadata.create_all
-            async with self.engine.begin() as conn:
-                await conn.run_sync(PLANAR_APPLICATION_METADATA.create_all)
-
-        else:
-            async with self.engine.begin() as conn:
-                await self._setup_database()
-                await conn.run_sync(PLANAR_FRAMEWORK_METADATA.create_all)
-                await conn.run_sync(PLANAR_APPLICATION_METADATA.create_all)
+        logger.info("starting database migration with alembic")
+        await self._setup_database()
+        await self._run_system_migrations()
+        # For now user migrations are not supported, so we fall back to SQLModel.metadata.create_all
+        async with self.engine.begin() as conn:
+            await conn.run_sync(PLANAR_APPLICATION_METADATA.create_all)

planar/dependencies.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+import sys
+from importlib import import_module
+from typing import Mapping, Tuple
+
+
+# mapping: public_name -> (relative_submodule, attribute_in_submodule)
+# This is a PEP 562 compliant way to lazily import modules
+# which is a way to avoid circular dependencies in __init__.py.
+def lazy_exports(module_name: str, mapping: Mapping[str, Tuple[str, str]]) -> None:
+    mod = sys.modules[module_name]
+    mod.__all__ = list(mapping.keys())  # type: ignore
+
+    def __getattr__(name: str):
+        try:
+            submod, attr = mapping[name]
+        except KeyError:
+            raise AttributeError(
+                f"module {module_name!r} has no attribute {name!r}"
+            ) from None
+        obj = getattr(import_module(submod, module_name), attr)
+        setattr(mod, name, obj)  # cache
+        return obj
+
+    def __dir__():
+        return sorted(set(mod.__dict__.keys()) | set(mod.__all__))
+
+    mod.__getattr__ = __getattr__  # PEP 562
+    mod.__dir__ = __dir__

planar/files/test_files.py

@@ -19,15 +19,14 @@ from planar.workflows.decorators import workflow
 from planar.workflows.execution import execute
 from planar.workflows.models import Workflow
 
-app = PlanarApp(
-    config=sqlite_config(":memory:"),
-    title="Planar app for testing file workflows",
-    description="Testing",
-)
-
 
 @pytest.fixture(name="app")
-def app_fixture():
+def app_fixture(tmp_db_path: str):
+    app = PlanarApp(
+        config=sqlite_config(tmp_db_path),
+        title="Planar app for testing file workflows",
+        description="Testing",
+    )
     yield app
 
 

planar/modeling/mixins/test_auditable.py

@@ -37,10 +37,10 @@ class TestAuditableModel(AuditableMixin, SQLModel, table=True):
 
 
 @pytest.fixture
-async def session(mem_db_engine):
+async def session(tmp_db_engine):
     """Create a database session."""
 
-    async with new_session(mem_db_engine) as session:
+    async with new_session(tmp_db_engine) as session:
         await (await session.connection()).run_sync(SQLModel.metadata.create_all)
         yield session
 

planar/modeling/orm/planar_base_entity.py

@@ -12,7 +12,10 @@ from .reexports import SQLModel
 logger = get_logger("orm.PlanarBaseEntity")
 
 
-PLANAR_APPLICATION_METADATA = MetaData()
+# Default schema for all entity / user tables, but can be overridden by the user
+# in planar configuration, which db.py uses.
+PLANAR_ENTITY_SCHEMA = "planar_entity"
+PLANAR_APPLICATION_METADATA = MetaData(schema=PLANAR_ENTITY_SCHEMA)
 
 
 class PlanarBaseEntity(UUIDPrimaryKeyMixin, AuditableMixin, SQLModel, table=False):

planar/routers/agents_router.py

@@ -1,12 +1,13 @@
 import asyncio
-from typing import Any
+import json
+from typing import Any, AsyncGenerator
 
 from fastapi import APIRouter, BackgroundTasks, HTTPException
 from fastapi.responses import StreamingResponse
 from pydantic import BaseModel
 
-from planar.ai.agent_utils import AgentEventEmitter, AgentEventType, agent_configuration
-from planar.ai.models import AgentConfig
+from planar.ai.agent_utils import agent_configuration
+from planar.ai.models import AgentConfig, AgentEventEmitter, AgentEventType
 from planar.ai.utils import AgentSerializeable, serialize_agent
 from planar.logging import get_logger
 from planar.object_config.object_config import ConfigValidationError
@@ -17,6 +18,7 @@ from planar.security.authorization import (
     validate_authorization_for,
 )
 from planar.session import get_engine, session_context
+from planar.utils import utc_now
 
 logger = get_logger(__name__)
 
@@ -29,6 +31,52 @@ class AgentSimulationData[T](BaseModel):
     input_value: str | T
 
 
+class SimulationAgentEvent:
+    def __init__(
+        self,
+        event_type: AgentEventType,
+        data: BaseModel | str | None,
+    ):
+        self.event_type = event_type
+        self.data = data
+        self.timestamp = utc_now().isoformat()
+
+
+class SimulationAgentEventEmitter(AgentEventEmitter):
+    def __init__(self):
+        self.queue: asyncio.Queue[SimulationAgentEvent] = asyncio.Queue()
+
+    def emit(self, event_type: AgentEventType, data: BaseModel | str | None):
+        event = SimulationAgentEvent(event_type, data)
+        self.queue.put_nowait(event)
+
+    async def get_events(self) -> AsyncGenerator[str, None]:
+        while True:
+            event = await self.queue.get()
+
+            if isinstance(event.data, BaseModel):
+                data = {
+                    "data": event.data.model_dump(),
+                    "event_type": event.event_type,
+                }
+            else:
+                data = {
+                    "data": event.data,
+                    "event_type": event.event_type,
+                }
+
+            yield f"data: {json.dumps(data)}\n\n"
+
+            self.queue.task_done()
+
+            if event.event_type in (AgentEventType.COMPLETED, AgentEventType.ERROR):
+                break
+
+    def is_empty(self) -> bool:
+        """Check if the queue is empty."""
+        return self.queue.empty()
+
+
 class AgentEvent(BaseModel):
     """Model representing a single event emitted by the agent."""
 
@@ -147,7 +195,7 @@ def create_agent_router(object_registry: ObjectRegistry) -> APIRouter:
             logger.warning("agent not found for simulation", agent_name=agent_name)
             raise HTTPException(status_code=404, detail="Agent not found")
 
-        emitter = AgentEventEmitter()
+        emitter = SimulationAgentEventEmitter()
 
         # Create a copy of the request data to avoid sharing data between tasks
         request_copy = request.model_copy()

planar/routers/test_agents_router.py

@@ -15,10 +15,10 @@ from planar.testing.planar_test_client import PlanarTestClient
 
 
 @pytest.fixture(name="app")
-def app_fixture():
+def app_fixture(tmp_db_path: str):
     """Create a test app with agents."""
     app = PlanarApp(
-        config=sqlite_config(":memory:"),
+        config=sqlite_config(tmp_db_path),
         title="Test app for agent router",
         description="Testing agent endpoints",
     )

planar/routers/test_files_router.py

@@ -10,9 +10,9 @@ from planar.testing.planar_test_client import PlanarTestClient
 
 
 @pytest.fixture(name="app")
-def app_fixture():
+def app_fixture(tmp_db_path: str):
     return PlanarApp(
-        config=sqlite_config(":memory:"),
+        config=sqlite_config(tmp_db_path),
         title="Test app for files router",
         description="Testing files endpoints",
     )

planar/routers/test_object_config_router.py

@@ -41,10 +41,10 @@ class OutputFromTestRule(BaseModel):
 
 
 @pytest.fixture(name="app")
-def app_fixture():
+def app_fixture(tmp_db_path: str):
     """Create a test app with agents and rules."""
     app = PlanarApp(
-        config=sqlite_config(":memory:"),
+        config=sqlite_config(tmp_db_path),
         title="Test app for object config router",
         description="Testing object configuration endpoints",
     )

planar/routers/test_routes_security.py

@@ -61,8 +61,9 @@ def restrictive_policy_file(tmp_path):
 
 
 @pytest.fixture(name="app_with_restricted_authz")
-def create_app_with_restricted_authz(restrictive_policy_file):
-    config = sqlite_config("test_authz_router.db")
+def create_app_with_restricted_authz(tmp_path, restrictive_policy_file):
+    db_path = tmp_path / "test_authz_router.db"
+    config = sqlite_config(str(db_path))
     config.security = SecurityConfig(
         authz=AuthzConfig(enabled=True, policy_file=restrictive_policy_file)
     )

planar/routers/test_rule_router.py

@@ -83,9 +83,9 @@ def pricing_rule_with_wrong_type(
 
 
 @pytest.fixture(name="app")
-def app_fixture():
+def app_fixture(tmp_db_path: str):
     app = PlanarApp(
-        config=sqlite_config(":memory:"),
+        config=sqlite_config(tmp_db_path),
         title="Test app for agent router",
         description="Testing agent endpoints",
     )

planar/routers/test_workflow_router.py

@@ -120,18 +120,16 @@ async def file_processing_workflow(file: PlanarFile):
     )
 
 
-app = PlanarApp(
-    config=sqlite_config("test_workflow_router.db"),
-    title="Test Workflow Router API",
-    description="API for testing workflow routers",
-)
-
-
 # ------ TESTS ------
 
 
 @pytest.fixture(name="app")
-def app_fixture():
+def app_fixture(tmp_db_path: str):
+    app = PlanarApp(
+        config=sqlite_config(tmp_db_path),
+        title="Test Workflow Router API",
+        description="API for testing workflow routers",
+    )
     # Re-register workflows since ObjectRegistry gets reset before each test
     app.register_workflow(expense_approval_workflow)
     app.register_workflow(file_processing_workflow)

planar/rules/__init__.py

@@ -1,23 +1,17 @@
-import importlib
-from typing import Any
+from typing import TYPE_CHECKING, Mapping, Tuple
 
-_DEFERRED_IMPORTS = {
-    "rule": ".decorator",
-    "Rule": ".models",
-    "RuleSerializeable": ".models",
+from planar.dependencies import lazy_exports
+
+_DEFERRED_IMPORTS: Mapping[str, Tuple[str, str]] = {
+    "rule": (".decorator", "rule"),
+    "Rule": (".models", "Rule"),
+    "RuleSerializeable": (".models", "RuleSerializeable"),
 }
 
+if TYPE_CHECKING:
+    from .decorator import rule
+    from .models import Rule, RuleSerializeable
 
-def __getattr__(name: str) -> Any:
-    """
-    Lazily import modules to avoid circular dependencies.
-    This is called by the Python interpreter when a module attribute is accessed
-    that cannot be found in the module's __dict__.
-    PEP 562
-    """
-    if name in _DEFERRED_IMPORTS:
-        module_path = _DEFERRED_IMPORTS[name]
-        module = importlib.import_module(module_path, __name__)
-        return getattr(module, name)
+    __all__ = ["Rule", "RuleSerializeable", "rule"]
 
-    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+lazy_exports(__name__, _DEFERRED_IMPORTS)

planar/scaffold_templates/app/flows/process_invoice.py.j2

@@ -1,5 +1,4 @@
 from planar.ai import Agent
-from planar.ai.providers import OpenAI
 from planar.files import PlanarFile
 from planar.human import Human
 from planar.rules.decorator import rule
@@ -23,7 +22,7 @@ class RuleOutput(BaseModel):
 
 invoice_agent = Agent(
     name="Invoice Agent",
-    model=OpenAI.gpt_4_1,
+    model="openai:gpt-4.1",
     tools=[],
     max_turns=1,
     system_prompt="Extract vendor and amount from invoice text.",

planar/scaffold_templates/planar.dev.yaml.j2

@@ -32,3 +32,12 @@ logging:
   # the following lines to enable INFO level for the whole application (except sqlalchemy.engine, which must be enabled above)
   # "":
   #  level: INFO
+
+# Uncomment to enable data features with Ducklake
+# data:
+#   catalog:
+#     type: duckdb
+#     path: .data/catalog.ducklake
+#   storage:
+#     backend: localdir
+#     directory: .data/ducklake_files

planar/scaffold_templates/planar.prod.yaml.j2

@@ -30,3 +30,17 @@ security:
 ai_providers:
   openai:
     api_key: ${OPENAI_API_KEY}
+
+# Uncomment to enable data features with Ducklake
+# data:
+#   catalog:
+#     type: postgres
+#     host: ${DB_HOST}
+#     port: ${DB_PORT}
+#     user: ${DB_USER}
+#     password: ${DB_PASSWORD}
+#     db: ducklake_catalog
+#   storage:
+#     backend: s3
+#     region: us-west-2
+#     bucket_name: ${S3_DATA_BUCKET}

planar/scaffold_templates/pyproject.toml.j2

@@ -3,8 +3,8 @@ name = "{{ name }}"
 version = "0.1.0"
 requires-python = ">=3.12"
 dependencies = [
-    "planar>=0.6.0",
+    "planar>=0.9.0",
 ]
 
 [[tool.uv.index]]
-url = "https://coplane.github.io/planar/simple/"
+url = "https://coplane.github.io/planar/simple/"

planar/test_sqlalchemy.py

@@ -3,7 +3,7 @@ from uuid import uuid4
 import pytest
 from sqlalchemy.exc import DBAPIError
 from sqlalchemy.ext.asyncio import AsyncEngine
-from sqlmodel import col, insert, select
+from sqlmodel import col, insert, select, text
 
 from planar.db import PlanarSession, new_session
 from planar.modeling.orm.planar_base_entity import PlanarBaseEntity
@@ -156,3 +156,38 @@ async def test_serializable_transaction_failure_1(tmp_db_engine: AsyncEngine):
         # Session 2: Commit should fail with serialization error
         with pytest.raises(DBAPIError, match="could not serialize access"):
             await session2.commit()
+
+
+async def test_entity_schema_and_planar_schema_presence(tmp_db_engine: AsyncEngine):
+    table_name = SomeModel.__tablename__
+
+    async with new_session(tmp_db_engine) as session:
+        dialect = session.dialect.name
+
+        if dialect == "postgresql":
+            # Verify schemas include 'planar' and the default entity schema 'planar_entity'
+            res = await session.exec(
+                text("select schema_name from information_schema.schemata")  # type: ignore[arg-type]
+            )
+            schemas = {row[0] for row in res}
+            assert "planar" in schemas
+            assert "planar_entity" in schemas
+
+            # Verify SomeModel table is created in the entity schema
+            res = await session.exec(
+                text(
+                    "select table_schema from information_schema.tables where table_name = :tn"
+                ).bindparams(tn=table_name)  # type: ignore[arg-type]
+            )
+            table_schemas = {row[0] for row in res}
+            assert "planar_entity" in table_schemas
+            assert "public" not in table_schemas
+
+        else:
+            # SQLite: no schemas; ensure table exists
+            res = await session.exec(
+                text("select name from sqlite_master where type='table'")  # type: ignore[arg-type]
+            )
+            tables = {row[0] for row in res}
+            assert table_name in tables
+            assert not any(name.startswith("planar.") for name in tables)

planar/testing/fixtures.py

@@ -254,23 +254,9 @@ async def tmp_db_engine(tmp_db_url: str):
         yield engine
 
 
-@pytest.fixture()
-async def mem_db_engine(tmp_db_engine):
-    # Memory databases don't work well with aiosqlite due to the "database
-    # table is locked" error (which doesn't respect timeouts), so just use a
-    # temporary db file for now until we figure out a fix.
-    yield tmp_db_engine
-
-    # name = uuid4()
-    # async with engine_context(
-    #     f"sqlite+aiosqlite:///file:{name}?mode=memory&cache=shared&uri=true"
-    # ) as engine:
-    #     yield engine
-
-
 @pytest.fixture(name="session")
-async def session_fixture(mem_db_engine):
-    async with new_session(mem_db_engine) as session:
+async def session_fixture(tmp_db_engine):
+    async with new_session(tmp_db_engine) as session:
         tok = session_var.set(session)
         yield session
         session_var.reset(tok)
@@ -318,7 +304,7 @@ async def tracer_fixture():
 async def engine_context(url: str):
     db_manager = DatabaseManager(url)
     db_manager.connect()
-    await db_manager.migrate(use_alembic=True)
+    await db_manager.migrate()
     engine = db_manager.get_engine()
     tok = engine_var.set(engine)
     yield engine

planar/testing/workflow_observer.py

@@ -21,9 +21,9 @@ class WorkflowObserver:
     ) -> UUID:
         """Extract workflow_id from notification data"""
         if isinstance(notification.data, Workflow):
-            return notification.data.id
+            return notification.workflow_id
         else:
-            return notification.data.workflow_id
+            return notification.workflow_id
 
     def on_workflow_notification(self, notification: WorkflowNotification):
         workflow_id = UUID(str(self._get_workflow_id_from_notification(notification)))

planar/workflows/notifications.py

@@ -2,10 +2,12 @@ from contextlib import asynccontextmanager
 from contextvars import ContextVar
 from enum import Enum
 from typing import Callable, Union
+from uuid import UUID
 
 from pydantic import BaseModel
 
 from planar.logging import get_logger
+from planar.workflows.context import get_context
 from planar.workflows.models import Workflow, WorkflowStep
 
 logger = get_logger(__name__)
@@ -20,11 +22,19 @@ class Notification(str, Enum):
     STEP_RUNNING = "step-running"
     STEP_SUCCEEDED = "step-succeeded"
     STEP_FAILED = "step-failed"
+    AGENT_TEXT = "agent-text"
+    AGENT_THINK = "agent-think"
+
+
+class AgentEventData(BaseModel):
+    data: str
+    step_id: int
 
 
 class WorkflowNotification(BaseModel):
     kind: Notification
-    data: Union[Workflow, WorkflowStep]
+    workflow_id: UUID
+    data: Union[Workflow, WorkflowStep, AgentEventData]
 
 
 WorkflowNotificationCallback = Callable[[WorkflowNotification], None]
@@ -38,7 +48,9 @@ def workflow_notify(workflow: Workflow, kind: Notification):
     callback = workflow_notification_callback_var.get(None)
     if callback is not None:
         logger.debug("notifying workflow event", kind=kind, workflow_id=workflow.id)
-        callback(WorkflowNotification(kind=kind, data=workflow))
+        callback(
+            WorkflowNotification(kind=kind, workflow_id=workflow.id, data=workflow)
+        )
 
 
 def workflow_started(workflow: Workflow):
@@ -70,7 +82,9 @@ def step_notify(step: WorkflowStep, kind: Notification):
             workflow_id=step.workflow_id,
             step_id=step.step_id,
         )
-        callback(WorkflowNotification(kind=kind, data=step))
+        callback(
+            WorkflowNotification(kind=kind, workflow_id=step.workflow_id, data=step)
+        )
 
 
 def step_running(step: WorkflowStep):
@@ -85,6 +99,28 @@ def step_failed(step: WorkflowStep):
     return step_notify(step, Notification.STEP_FAILED)
 
 
+def agent_notify(kind: Notification, data: str):
+    callback = workflow_notification_callback_var.get(None)
+    if callback is not None:
+        context = get_context()
+        logger.debug("notifying agent event", kind=kind)
+        callback(
+            WorkflowNotification(
+                kind=kind,
+                workflow_id=context.workflow_id,
+                data=AgentEventData(data=data, step_id=context.step_stack[-1].step_id),
+            )
+        )
+
+
+def agent_think(data: str):
+    agent_notify(Notification.AGENT_THINK, data)
+
+
+def agent_text(data: str):
+    agent_notify(Notification.AGENT_TEXT, data)
+
+
 @asynccontextmanager
 async def workflow_notification_context(callback: WorkflowNotificationCallback):
     """Context manager for setting up and tearing down Workflow notification context"""