planar 0.10.0__py3-none-any.whl → 0.12.0__py3-none-any.whl

planar/db/alembic.ini

@@ -70,7 +70,7 @@ version_path_separator = os
 # so it sometimes incorrectly thinks it needs to re-generate things (like indices) that already
 # exist in the database from a prior migration. Using postgres obviates that issue.
 # https://github.com/sqlalchemy/alembic/issues/555
-sqlalchemy.url = postgresql+psycopg2://postgres:postgres@localhost:5432/postgres
+sqlalchemy.url = postgresql+asyncpg://postgres:postgres@localhost:5432/postgres
 
 # [post_write_hooks]
 # This section defines scripts or Python functions that are run

planar/files/storage/config.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING, Annotated, Literal
 
-from pydantic import BaseModel, Field, model_validator
+from pydantic import BaseModel, ConfigDict, Field, model_validator
 
 from .local_directory import LocalDirectoryStorage
 from .s3 import S3Storage
@@ -15,6 +15,8 @@ class LocalDirectoryConfig(BaseModel):
     backend: Literal["localdir"]
     directory: str
 
+    model_config = ConfigDict(frozen=True)
+
 
 class S3Config(BaseModel):
     backend: Literal["s3"]
@@ -25,6 +27,8 @@ class S3Config(BaseModel):
     endpoint_url: str | None = None
     presigned_url_ttl: int = 3600
 
+    model_config = ConfigDict(frozen=True)
+
 
 class AzureBlobConfig(BaseModel):
     backend: Literal["azure_blob"]
@@ -39,6 +43,8 @@ class AzureBlobConfig(BaseModel):
     # Common settings
     sas_ttl: int = 3600  # SAS URL expiry time in seconds
 
+    model_config = ConfigDict(frozen=True)
+
     @model_validator(mode="after")
     def validate_auth_config(self):
         """Ensure exactly one valid authentication configuration."""

planar/routers/dataset_router.py

@@ -12,6 +12,7 @@ from planar.data.exceptions import DatasetNotFoundError
 from planar.data.utils import (
     get_dataset,
     get_dataset_metadata,
+    get_datasets_metadata,
     list_datasets,
     list_schemas,
 )
@@ -51,9 +52,12 @@ def create_dataset_router() -> APIRouter:
         validate_authorization_for(DatasetResource(), DatasetAction.DATASET_LIST)
         datasets = await list_datasets(limit, offset)
 
+        dataset_names = [dataset.name for dataset in datasets]
+        metadata_by_dataset = await get_datasets_metadata(dataset_names, schema_name)
+
         response = []
         for dataset in datasets:
-            metadata = await get_dataset_metadata(dataset.name, schema_name)
+            metadata = metadata_by_dataset.get(dataset.name)
 
             if not metadata:
                 continue

planar/routers/info.py

@@ -1,16 +1,34 @@
+from typing import Literal, TypedDict
+
 from fastapi import APIRouter, Depends
 from pydantic import BaseModel
-from sqlalchemy.ext.asyncio import AsyncSession
-from sqlmodel import col, distinct, func, select
+from sqlmodel import col, func, select
+from sqlmodel.ext.asyncio.session import AsyncSession
 
+from planar.config import PlanarConfig, get_environment
+from planar.data.config import DataConfig
+from planar.files.storage.config import StorageConfig
 from planar.human.models import HumanTask, HumanTaskStatus
 from planar.logging import get_logger
-from planar.object_config import ConfigurableObjectType, ObjectConfiguration
+from planar.object_registry import ObjectRegistry
 from planar.session import get_session
+from planar.version import FALLBACK_VERSION, get_version
 from planar.workflows.models import Workflow, WorkflowStatus
 
 logger = get_logger(__name__)
 
+StorageInfo = Literal["s3", "localdir", "azure_blob"]
+
+
+class DatasetsInfo(BaseModel):
+    catalog: Literal["duckdb", "postgres", "sqlite"]
+    storage: StorageInfo
+
+
+class SystemFeatures(BaseModel):
+    storage: StorageInfo | None = None
+    datasets: DatasetsInfo | None = None
+
 
 class SystemInfo(BaseModel):
     """Combined application information and system statistics"""
@@ -19,6 +37,11 @@ class SystemInfo(BaseModel):
     title: str
     description: str
 
+    version: str
+    environment: str
+
+    features: SystemFeatures
+
     # System stats
     total_workflow_runs: int = 0
     completed_runs: int = 0
@@ -27,7 +50,18 @@ class SystemInfo(BaseModel):
     active_agents: int = 0
 
 
-async def get_system_stats(session: AsyncSession = Depends(get_session)) -> dict:
+class SystemStats(TypedDict):
+    total_workflow_runs: int
+    completed_runs: int
+    in_progress_runs: int
+    pending_human_tasks: int
+    active_agents: int
+
+
+async def get_system_stats(
+    registry: ObjectRegistry,
+    session: AsyncSession = Depends(get_session),
+) -> SystemStats:
     """
     Get system-wide statistics directly from the database.
 
@@ -35,8 +69,10 @@ async def get_system_stats(session: AsyncSession = Depends(get_session)) -> dict
     rather than fetching all records and calculating in the application.
     """
     try:
+        agent_count = len(registry.get_agents())
+
         # Get workflow run counts
-        workflow_stats = await session.execute(
+        workflow_stats = await session.exec(
             select(
                 func.count().label("total_runs"),
                 func.count(col(Workflow.id))
@@ -47,42 +83,21 @@ async def get_system_stats(session: AsyncSession = Depends(get_session)) -> dict
                 .label("in_progress_runs"),
             ).select_from(Workflow)
         )
-        workflow_row = workflow_stats.one()
+        total_runs, completed_runs, in_progress_runs = workflow_stats.one()
 
         # Get pending human task count
-        human_task_query = await session.execute(
+        human_task_query = await session.exec(
             select(func.count())
             .select_from(HumanTask)
             .where(HumanTask.status == HumanTaskStatus.PENDING)
         )
-        pending_tasks = human_task_query.scalar() or 0
-
-        # Get agent count from the registry or count distinct agent configs
-        agent_count = 0
-        try:
-            # Count distinct agent names in the AgentConfig table
-            agent_query = await session.execute(
-                select(
-                    func.count(distinct(ObjectConfiguration.object_name))
-                ).select_from(
-                    select(ObjectConfiguration)
-                    .where(
-                        ObjectConfiguration.object_type == ConfigurableObjectType.AGENT
-                    )
-                    .subquery()
-                )
-            )
-            agent_count = agent_query.scalar() or 0
-        except Exception:
-            logger.exception("error counting agents")
-            # Fallback to 0
-            agent_count = 0
+        pending_tasks = human_task_query.one()
 
         # Return stats dict
         return {
-            "total_workflow_runs": workflow_row.total_runs or 0,
-            "completed_runs": workflow_row.completed_runs or 0,
-            "in_progress_runs": workflow_row.in_progress_runs or 0,
+            "total_workflow_runs": total_runs,
+            "completed_runs": completed_runs,
+            "in_progress_runs": in_progress_runs,
             "pending_human_tasks": pending_tasks,
             "active_agents": agent_count,
         }
@@ -98,13 +113,23 @@ async def get_system_stats(session: AsyncSession = Depends(get_session)) -> dict
         }
 
 
-def create_info_router(title: str, description: str) -> APIRouter:
+def get_storage_info(cfg: StorageConfig) -> StorageInfo:
+    return cfg.backend
+
+
+def get_datasets_info(cfg: DataConfig) -> DatasetsInfo | None:
+    return DatasetsInfo(catalog=cfg.catalog.type, storage=get_storage_info(cfg.storage))
+
+
+def create_info_router(
+    title: str, description: str, config: PlanarConfig, registry: ObjectRegistry
+) -> APIRouter:
     """
     Create a router for serving combined application information and system statistics.
 
     This router provides a single endpoint to retrieve the application's title,
     description, and system-wide statistics on workflow runs, human tasks,
-    and registered agents.
+    and registered agents, as well as the application's features and configuration.
 
     Args:
         title: The application title
@@ -125,7 +150,25 @@ def create_info_router(title: str, description: str) -> APIRouter:
         Returns:
             SystemInfo object containing app details and system stats
         """
-        stats = await get_system_stats(session)
-        return SystemInfo(title=title, description=description, **stats)
+        stats = await get_system_stats(registry, session)
+        version = get_version()
+        if version == FALLBACK_VERSION:
+            logger.warning(
+                "planar package version not found",
+                package_name="planar",
+                fallback_version=FALLBACK_VERSION,
+            )
+
+        return SystemInfo(
+            title=title,
+            description=description,
+            version=version,
+            environment=get_environment(),
+            features=SystemFeatures(
+                storage=get_storage_info(config.storage) if config.storage else None,
+                datasets=get_datasets_info(config.data) if config.data else None,
+            ),
+            **stats,
+        )
 
     return router

planar/scaffold_templates/pyproject.toml.j2

@@ -3,7 +3,7 @@ name = "{{ name }}"
 version = "0.1.0"
 requires-python = ">=3.12"
 dependencies = [
-    "planar>=0.9.0",
+    "planar[data]>=0.10.0",
 ]
 
 [[tool.uv.index]]

planar/testing/fixtures.py

@@ -36,7 +36,7 @@ from pathlib import Path
 import pytest
 
 from planar.app import PlanarApp
-from planar.config import load_config
+from planar.config import load_config, load_environment_aware_config
 from planar.data.config import DataConfig, SQLiteCatalogConfig
 from planar.db import DatabaseManager, new_session
 from planar.files.storage.config import LocalDirectoryConfig
@@ -138,9 +138,12 @@ def data_config(tmp_path):
 @pytest.fixture(name="app_with_data")
 def app_with_data_fixture(data_config):
     """Create a PlanarApp with data configuration."""
-    app = PlanarApp()
-    # Add data config to the app's config
-    app.config.data = data_config
+    config = load_environment_aware_config()
+
+    config.data = data_config
+
+    app = PlanarApp(config=config)
+
     return app
 
 

planar/testing/planar_test_client.py

@@ -41,6 +41,14 @@ async def planar_test_client(
                     session_var.reset(token)
     await wait_all_event_loop_tasks()
 
+    if getattr(app.config, "data", None):
+        try:
+            from planar.data.connection import reset_connection_cache
+        except ImportError:
+            pass
+        else:
+            await reset_connection_cache()
+
 
 async def wait_all_event_loop_tasks():
     # Workaround prevent the event loop from exiting before aiosqlite

planar/version.py

@@ -0,0 +1,27 @@
+"""Utilities for working with Planar package version information."""
+
+from functools import lru_cache
+from importlib import metadata
+from typing import Final
+
+PACKAGE_NAME: Final[str] = "planar"
+FALLBACK_VERSION: Final[str] = "0.0.0.dev0"
+
+
+@lru_cache(maxsize=1)
+def get_version(
+    fallback: str = FALLBACK_VERSION,
+) -> str:
+    """Return the installed Planar version or a fallback value.
+
+    Args:
+        fallback: Value returned if the package metadata is unavailable.
+
+    Returns:
+        The package version string if available, otherwise the fallback value.
+    """
+
+    try:
+        return metadata.version(PACKAGE_NAME)
+    except metadata.PackageNotFoundError:
+        return fallback

planar-0.12.0.dist-info/METADATA

@@ -0,0 +1,202 @@
+Metadata-Version: 2.4
+Name: planar
+Version: 0.12.0
+Summary: Batteries-included framework for building durable agentic workflows and business applications.
+License-Expression: LicenseRef-Proprietary
+Requires-Dist: aiofiles>=24.1.0
+Requires-Dist: aiosqlite>=0.21.0
+Requires-Dist: alembic>=1.14.1
+Requires-Dist: anthropic>=0.49.0
+Requires-Dist: asyncpg
+Requires-Dist: boto3>=1.39.15
+Requires-Dist: cedarpy>=4.1.0
+Requires-Dist: fastapi[standard]>=0.115.7
+Requires-Dist: inflection>=0.5.1
+Requires-Dist: openai>=1.75
+Requires-Dist: pydantic-ai-slim[anthropic,bedrock,google,openai]>=0.7.5
+Requires-Dist: pygments>=2.19.1
+Requires-Dist: pyjwt[crypto]
+Requires-Dist: python-multipart>=0.0.20
+Requires-Dist: sqlalchemy[asyncio]>=2.0.37
+Requires-Dist: sqlmodel>=0.0.22
+Requires-Dist: typer>=0.15.2
+Requires-Dist: typing-extensions>=4.12.2
+Requires-Dist: zen-engine>=0.40.0
+Requires-Dist: azure-storage-blob>=12.19.0 ; extra == 'azure'
+Requires-Dist: azure-identity>=1.15.0 ; extra == 'azure'
+Requires-Dist: aiohttp>=3.8.0 ; extra == 'azure'
+Requires-Dist: ducklake>=0.1.1 ; extra == 'data'
+Requires-Dist: ibis-framework[duckdb]>=10.8.0 ; extra == 'data'
+Requires-Dist: polars>=1.31.0 ; extra == 'data'
+Requires-Dist: opentelemetry-api>=1.34.1 ; extra == 'otel'
+Requires-Dist: opentelemetry-exporter-otlp>=1.34.1 ; extra == 'otel'
+Requires-Dist: opentelemetry-instrumentation-logging>=0.55b1 ; extra == 'otel'
+Requires-Dist: opentelemetry-sdk>=1.34.1 ; extra == 'otel'
+Requires-Python: >=3.12
+Provides-Extra: azure
+Provides-Extra: data
+Provides-Extra: otel
+Description-Content-Type: text/markdown
+
+# Planar
+
+Planar is a batteries-included Python framework for building durable workflows, agent automations, and stateful APIs. Built on FastAPI and SQLModel, it combines orchestration, data modeling, and file management into a cohesive developer experience.
+
+## Feature Highlights
+
+- Durable workflow engine with resumable async steps, automatic retries, and suspension points
+- Agent step framework with first-class support for OpenAI, Anthropic, and other providers
+- Human task assignments and rule engine tooling baked into workflow execution
+- SQLModel-powered data layer with Alembic migrations and CRUD scaffolding out of the box
+- Built-in file management and storage adapters for local disk, Amazon S3, and Azure Blob Storage
+- CLI-driven developer workflow with templated scaffolding, hot reload, and environment-aware configuration
+
+## Installation
+
+Planar is published on PyPI. Add it to an existing project with `uv`:
+
+```bash
+uv add planar
+```
+
+To explore the CLI without updating `pyproject.toml`, use the ephemeral uvx runner:
+
+```bash
+uvx planar --help
+```
+
+## Quickstart
+
+Generate a new service, start up the dev server, and inspect the auto-generated APIs:
+
+```bash
+uvx planar scaffold --name my_service
+cd my_service
+uv run planar dev src/main.py
+```
+
+Open `http://127.0.0.1:8000/docs` to explore your service's routes and workflow endpoints. The scaffold prints the exact app path if it differs from `src/main.py`.
+
+## Define a Durable Workflow
+
+```python
+from datetime import timedelta
+
+from planar import PlanarApp
+from planar.workflows import step, suspend, workflow
+
+@step
+async def charge_customer(order_id: str) -> None:
+    ...
+
+@step
+async def notify_success(order_id: str) -> None:
+    ...
+
+@workflow
+async def process_order(order_id: str) -> None:
+    await charge_customer(order_id)
+    await suspend(interval=timedelta(hours=1))
+    await notify_success(order_id)
+
+
+app = PlanarApp()
+app.register_workflow(process_order)
+```
+
+Workflows are async functions composed of resumable steps. Planar persists every step, applies configurable retry policies, and resumes suspended workflows even after process restarts. Check `docs/workflows.md` for deeper concepts including event-driven waits, human steps, and agent integrations.
+
+## Core Capabilities
+
+- **Workflow orchestration**: Compose async steps with guaranteed persistence, scheduling, and concurrency control.
+- **Agent steps**: Run LLM-powered actions durably with provider-agnostic adapters and structured prompts.
+- **Human tasks and rules**: Build human-in-the-loop approvals and declarative rule evaluations alongside automated logic.
+- **Stateful data and files**: Model entities with SQLModel, manage migrations through Alembic, and store files using pluggable backends.
+- **Observability**: Structured logging and OpenTelemetry hooks surface workflow progress and performance metrics.
+
+## Command Line Interface
+
+```bash
+uvx planar scaffold --help   # generate a new project from the official template
+uv run planar dev [PATH]     # run with hot reload and development defaults
+uv run planar prod [PATH]    # run with production defaults
+```
+
+`[PATH]` points to the module that exports a `PlanarApp` instance (defaults to `app.py` or `main.py`). Use `--config PATH` to load a specific configuration file and `--app NAME` if your application variable is not named `app`.
+
+## Configuration
+
+Planar merges environment defaults with an optional YAML override. By convention it looks for `planar.dev.yaml`, `planar.prod.yaml`, or `planar.yaml` in your project directory, but you can supply a path explicitly via `--config` or the `PLANAR_CONFIG` environment variable.
+
+Example minimal override:
+
+```yaml
+ai_providers:
+  openai:
+    api_key: ${OPENAI_API_KEY}
+
+storage:
+  directory: .files
+```
+
+For more configuration patterns and workflow design guidance, browse the documents in `docs/`.
+
+## Examples
+
+- `examples/expense_approval_workflow` — human approvals with AI agent collaboration
+- `examples/event_based_workflow` — event-driven orchestration and external wakeups
+- `examples/simple_service` — CRUD service paired with workflows
+
+Run any example with `uv run planar dev path/to/main.py`.
+
+## Local Development
+
+Planar is built with `uv`. Clone the repository and install dev dependencies:
+
+```bash
+uv sync --extra otel
+```
+
+Useful commands:
+
+- `uv run ruff check --fix` and `uv run ruff format` to lint and format
+- `uv run pyright` for static type checking
+- `uv run pytest` to run the test suite (use `-n auto` for parallel execution)
+- `uv run pytest --cov=planar` to collect coverage
+- `uv tool install pre-commit && uv tool run pre-commit install` to enable git hooks
+
+### PostgreSQL Test Suite
+
+```bash
+docker run --restart=always --name planar-postgres \
+  -e POSTGRES_PASSWORD=postgres \
+  -p 127.0.0.1:5432:5432 \
+  -d docker.io/library/postgres
+
+PLANAR_TEST_POSTGRESQL=1 PLANAR_TEST_POSTGRESQL_CONTAINER=planar-postgres \
+  uv run pytest -s
+```
+
+Disable SQLite with `PLANAR_TEST_SQLITE=0`.
+
+### Cairo SVG Dependencies
+
+Some AI integration tests convert SVG assets using `cairosvg`. Install Cairo libraries locally before running those tests:
+
+```bash
+brew install cairo libffi pkg-config
+export DYLD_FALLBACK_LIBRARY_PATH="/opt/homebrew/lib:${DYLD_FALLBACK_LIBRARY_PATH}"
+```
+
+Most Linux distributions ship the required libraries via their package manager.
+
+## Documentation
+
+Dive deeper into Planar's design and APIs in the `docs/` directory:
+
+- `docs/workflows.md`
+- `docs/design/event_based_waiting.md`
+- `docs/design/human_step.md`
+- `docs/design/agent_step.md`
+
+For agentic coding tools, use `docs/llm_prompt.md` as a drop-in reference document in whatever tool you are using.