planar 0.11.0__py3-none-any.whl → 0.13.0__py3-none-any.whl

planar/ai/__init__.py

@@ -6,10 +6,12 @@ from .agent_utils import (
     agent_configuration,
     get_agent_config,
 )
+from .tool_context import get_tool_context
 
 __all__ = [
     "Agent",
     "AgentRunResult",
     "agent_configuration",
     "get_agent_config",
+    "get_tool_context",
 ]

planar/ai/agent.py

@@ -50,8 +50,8 @@ class AgentWorkflowNotifier(AgentEventEmitter):
 class Agent[
     TInput: BaseModel | str,
     TOutput: BaseModel | str,
-    TDeps,
-](AgentBase[TInput, TOutput, TDeps]):
+    TToolContext,
+](AgentBase[TInput, TOutput, TToolContext]):
     model: models.KnownModelName | models.Model = "openai:gpt-4o"
 
     async def run_step(

planar/ai/agent_base.py

@@ -1,5 +1,3 @@
-from __future__ import annotations
-
 import abc
 from dataclasses import dataclass, field
 from typing import (
@@ -15,7 +13,7 @@ from pydantic import BaseModel
 from pydantic_ai.settings import ModelSettings
 
 from planar.ai.models import AgentConfig, AgentEventEmitter, AgentRunResult
-from planar.ai.state import delete_state, set_state
+from planar.ai.tool_context import clear_tool_context, set_tool_context
 from planar.logging import get_logger
 from planar.modeling.field_helpers import JsonSchema
 from planar.utils import P, R, T, U
@@ -30,7 +28,7 @@ class AgentBase[
     # TODO: add `= str` default when we upgrade to 3.13
     TInput: BaseModel | str,
     TOutput: BaseModel | str,
-    TState,
+    TToolContext,
 ](abc.ABC):
     """An LLM-powered agent that can be called directly within workflows."""
 
@@ -47,7 +45,7 @@ class AgentBase[
     )
     event_emitter: AgentEventEmitter | None = None
     durable: bool = True
-    state_type: Type[TState] | None = None
+    tool_context_type: Type[TToolContext] | None = None
 
     # TODO: move here to serialize to frontend
     #
@@ -94,16 +92,16 @@ class AgentBase[
 
     @overload
     async def __call__(
-        self: "AgentBase[TInput, str, TState]",
+        self: "AgentBase[TInput, str, TToolContext]",
         input_value: TInput,
-        state: TState | None = None,
+        tool_context: TToolContext | None = None,
     ) -> AgentRunResult[str]: ...
 
     @overload
     async def __call__(
-        self: "AgentBase[TInput, TOutput, TState]",
+        self: "AgentBase[TInput, TOutput, TToolContext]",
         input_value: TInput,
-        state: TState | None = None,
+        tool_context: TToolContext | None = None,
     ) -> AgentRunResult[TOutput]: ...
 
     def as_step_if_durable(
@@ -125,7 +123,7 @@ class AgentBase[
     async def __call__(
         self,
         input_value: TInput,
-        state: TState | None = None,
+        tool_context: TToolContext | None = None,
     ) -> AgentRunResult[Any]:
         if self.input_type is not None and not isinstance(input_value, self.input_type):
             raise ValueError(
@@ -153,22 +151,25 @@ class AgentBase[
                 return_type=AgentRunResult[self.output_type],
             )
 
-        if state is not None:
-            if self.state_type is None:
-                raise ValueError("state cannot be provided when state_type is not set")
-            if not isinstance(state, self.state_type):
+        if tool_context is not None:
+            if self.tool_context_type is None:
+                raise ValueError(
+                    "tool_context cannot be provided when tool_context_type is not set"
+                )
+            if not isinstance(tool_context, self.tool_context_type):
                 raise ValueError(
-                    f"state must be of type {self.state_type}, but got {type(state)}"
+                    f"tool_context must be of type {self.tool_context_type}, "
+                    f"but got {type(tool_context)}"
                 )
-            set_state(cast(TState, state))
+            set_tool_context(cast(TToolContext, tool_context))
 
         try:
             result = await run_step(input_value=input_value)
             # Cast the result to ensure type compatibility
             return cast(AgentRunResult[TOutput], result)
         finally:
-            if state is not None:
-                delete_state()
+            if tool_context is not None:
+                clear_tool_context()
 
     @abc.abstractmethod
     async def run_step(

planar/ai/{state.py → tool_context.py}

@@ -5,13 +5,13 @@ from planar.task_local import TaskLocal
 data: TaskLocal[Any] = TaskLocal()
 
 
-def set_state(ctx: Any):
+def set_tool_context(ctx: Any):
     return data.set(ctx)
 
 
-def get_state[T](_: Type[T]) -> T:
+def get_tool_context[T](_: Type[T]) -> T:
     return cast(T, data.get())
 
 
-def delete_state():
+def clear_tool_context():
     return data.clear()

planar/app.py

@@ -274,6 +274,14 @@ class PlanarApp:
             # Reset the config in the context
             config_var.reset(config_tok)
 
+            if self.config.data:
+                try:
+                    from planar.data.connection import reset_connection_cache
+                except ImportError as exc:  # pragma: no cover - optional dependency
+                    logger.debug("skipping data connection cleanup", error=str(exc))
+                else:
+                    await reset_connection_cache()
+
         await self.db_manager.disconnect()
 
         if self.storage:

planar/cli.py

@@ -2,6 +2,7 @@ import os
 import subprocess
 import sys
 from pathlib import Path
+from typing import Annotated
 
 import typer
 import uvicorn
@@ -9,10 +10,35 @@ from jinja2 import Environment as JinjaEnvironment
 from jinja2 import FileSystemLoader
 
 from planar.config import Environment
+from planar.version import get_version
 
 app = typer.Typer(help="Planar CLI tool")
 
 
+def version_callback(value: bool) -> bool:
+    if value:
+        typer.echo(f"planar {get_version()}")
+        raise typer.Exit()
+    return value
+
+
+@app.callback()
+def root_callback(
+    version: Annotated[
+        bool | None,
+        typer.Option(
+            "--version",
+            "-v",
+            help="Show Planar version and exit.",
+            callback=version_callback,
+            is_flag=True,
+            is_eager=True,
+        ),
+    ] = None,
+) -> None:
+    """Entry point for Planar CLI with shared options."""
+
+
 def find_default_app_path() -> Path:
     """Checks for default app file paths (app.py, then main.py)."""
     for filename in ["app.py", "main.py"]:
@@ -236,6 +262,11 @@ def run_command(
 def scaffold_project(
     name: str = typer.Option(None, "--name", help="Name of the new project"),
     directory: Path = typer.Option(Path("."), "--directory", help="Target directory"),
+    use_local_source: bool = typer.Option(
+        False,
+        "--use-local-source",
+        help="Use local planar source instead of published package (for development)",
+    ),
 ):
     """
     Creates a new Planar project with a basic structure and example workflow.
@@ -252,8 +283,19 @@ def scaffold_project(
     template_dir = Path(__file__).parent / "scaffold_templates"
     jinja_env = JinjaEnvironment(loader=FileSystemLoader(template_dir))
 
+    planar_source_path = None
+    if use_local_source:
+        # Assume we're running from the planar package itself
+        # Go up from planar/cli.py -> planar/ -> planar_repo/
+        planar_source_path = Path(__file__).parent.parent.resolve()
+        typer.echo(f"Using local planar source: {planar_source_path}")
+
     # Template context
-    context = {"name": name}
+    context = {
+        "name": name,
+        "local_source": use_local_source,
+        "planar_source_path": planar_source_path,
+    }
 
     # Create project structure
     try:

planar/config.py

@@ -3,6 +3,7 @@ import logging
 import logging.config
 import os
 import sys
+from contextlib import contextmanager
 from enum import Enum
 from pathlib import Path
 from typing import Annotated, Any, Dict, Literal
@@ -24,6 +25,7 @@ from sqlalchemy import URL, make_url
 from planar.data.config import DataConfig
 from planar.files.storage.config import LocalDirectoryConfig, StorageConfig
 from planar.logging import get_logger
+from planar.logging.formatter import StructuredFormatter
 
 logger = get_logger(__name__)
 
@@ -144,12 +146,12 @@ class CorsConfig(BaseModel):
     allow_headers: list[str]
 
     @model_validator(mode="after")
-    def validate_allow_origins(cls, instance):
-        if instance.allow_credentials and "*" in instance.allow_origins:
+    def validate_allow_origins(self):
+        if self.allow_credentials and "*" in self.allow_origins:
             raise ValueError(
                 "allow_credentials cannot be True if allow_origins includes '*'. Must explicitly specify allowed origins."
             )
-        return instance
+        return self
 
 
 LOCAL_CORS_CONFIG = CorsConfig(
@@ -173,10 +175,10 @@ class JWTConfig(BaseModel):
     additional_exclusion_paths: list[str] | None = Field(default_factory=list)
 
     @model_validator(mode="after")
-    def validate_client_id(cls, instance):
-        if not instance.client_id or not instance.org_id:
+    def validate_client_id(self):
+        if not self.client_id or not self.org_id:
             raise ValueError("Both client_id and org_id required to enable JWT")
-        return instance
+        return self
 
 
 # Coplane ORG JWT config
@@ -235,12 +237,12 @@ class PlanarConfig(BaseModel):
     model_config = ConfigDict(extra="forbid")
 
     @model_validator(mode="after")
-    def validate_db_connection_reference(cls, instance):
-        if instance.app.db_connection not in instance.db_connections:
+    def validate_db_connection_reference(self):
+        if self.app.db_connection not in self.db_connections:
             raise ValueError(
-                f"Invalid db_connection reference: {instance.app.db_connection}"
+                f"Invalid db_connection reference: {self.app.db_connection}"
             )
-        return instance
+        return self
 
     def connection_url(self) -> URL:
         connection = self.db_connections[self.app.db_connection]
@@ -460,6 +462,28 @@ def load_environment_aware_env_vars() -> None:
             return
 
 
+@contextmanager
+def _temporary_config_logging():
+    """Install a console handler so config loading logs are visible before configuration."""
+    root_logger = logging.getLogger()
+    handler = logging.StreamHandler(sys.stderr)
+    handler.setFormatter(StructuredFormatter(use_colors=sys.stderr.isatty()))
+    handler.setLevel(logging.NOTSET)
+
+    previous_level = root_logger.level
+    if root_logger.getEffectiveLevel() > logging.INFO:
+        root_logger.setLevel(logging.INFO)
+
+    root_logger.addHandler(handler)
+
+    try:
+        yield
+    finally:
+        root_logger.removeHandler(handler)
+        handler.close()
+        root_logger.setLevel(previous_level)
+
+
 def load_environment_aware_config[ConfigClass]() -> PlanarConfig:
     """
     Load configuration based on environment settings, using environment variables
@@ -476,83 +500,87 @@ def load_environment_aware_config[ConfigClass]() -> PlanarConfig:
     Raises:
         InvalidConfigurationError: If configuration loading or validation fails.
     """
-    load_environment_aware_env_vars()
-    env = get_environment()
-
-    if env == "dev":
-        base_config = sqlite_config(db_path="planar_dev.db")
-        base_config.security = SecurityConfig(cors=LOCAL_CORS_CONFIG)
-        base_config.environment = Environment.DEV
-    else:
-        base_config = sqlite_config(db_path="planar.db")
-        base_config.environment = Environment.PROD
-        base_config.security = SecurityConfig(
-            cors=PROD_CORS_CONFIG, jwt=JWT_COPLANE_CONFIG
-        )
+    with _temporary_config_logging():
+        load_environment_aware_env_vars()
+        env = get_environment()
+
+        if env == "dev":
+            base_config = sqlite_config(db_path="planar_dev.db")
+            base_config.security = SecurityConfig(cors=LOCAL_CORS_CONFIG)
+            base_config.environment = Environment.DEV
+        else:
+            base_config = sqlite_config(db_path="planar.db")
+            base_config.environment = Environment.PROD
+            base_config.security = SecurityConfig(
+                cors=PROD_CORS_CONFIG, jwt=JWT_COPLANE_CONFIG
+            )
 
-    # Convert base config to dict for merging
-    # Use by_alias=False to work with Python field names before validation
-    base_dict = base_config.model_dump(mode="python", by_alias=False)
+        # Convert base config to dict for merging
+        # Use by_alias=False to work with Python field names before validation
+        base_dict = base_config.model_dump(mode="python", by_alias=False)
 
-    override_config_path = get_config_path()
-    if override_config_path:
-        if not override_config_path.exists():
-            raise InvalidConfigurationError(
-                f"Configuration file not found: {override_config_path}"
+        override_config_path = get_config_path()
+        if override_config_path:
+            if not override_config_path.exists():
+                raise InvalidConfigurationError(
+                    f"Configuration file not found: {override_config_path}"
+                )
+        else:
+            paths_to_check = []
+            if os.environ.get("PLANAR_ENTRY_POINT"):
+                # Extract the directory from the entry point path
+                entry_point_dir = Path(os.environ["PLANAR_ENTRY_POINT"]).parent
+                paths_to_check = [
+                    entry_point_dir / f"planar.{env}.yaml",
+                    entry_point_dir / "planar.yaml",
+                ]
+            paths_to_check.append(Path(f"planar.{env}.yaml"))
+            paths_to_check.append(Path("planar.yaml"))
+
+            override_config_path = next(
+                (path for path in paths_to_check if path.exists()), None
             )
-    else:
-        paths_to_check = []
-        if os.environ.get("PLANAR_ENTRY_POINT"):
-            # Extract the directory from the entry point path
-            entry_point_dir = Path(os.environ["PLANAR_ENTRY_POINT"]).parent
-            paths_to_check = [
-                entry_point_dir / f"planar.{env}.yaml",
-                entry_point_dir / "planar.yaml",
-            ]
-        paths_to_check.append(Path(f"planar.{env}.yaml"))
-        paths_to_check.append(Path("planar.yaml"))
-
-        override_config_path = next(
-            (path for path in paths_to_check if path.exists()), None
-        )
-        if override_config_path is None:
-            logger.warning(
-                "no override config file found, using default config",
-                search_paths=[str(p) for p in paths_to_check],
-                env=env,
+            if override_config_path is None:
+                logger.warning(
+                    "no override config file found, using default config",
+                    search_paths=[str(p) for p in paths_to_check],
+                    env=env,
+                )
+
+        merged_dict = base_dict
+        if override_config_path and override_config_path.exists():
+            logger.info(
+                "using override config file", override_config_path=override_config_path
             )
+            try:
+                # We can't use load_config_from_file here because we expect
+                # the override config to not be a fully validated PlanarConfig object,
+                # and we need to merge it onto the base default config.
+                with open(override_config_path, "r") as f:
+                    override_yaml_str = f.read()
+
+                # Expand environment variables in the YAML string
+                processed_yaml_str = os.path.expandvars(override_yaml_str)
+                logger.debug(
+                    "processed override yaml string",
+                    processed_yaml_str=processed_yaml_str,
+                )
+
+                override_dict = yaml.safe_load(processed_yaml_str) or {}
+                logger.debug("loaded override config", override_dict=override_dict)
+
+                # Deep merge the override onto the base dictionary
+                merged_dict = deep_merge_dicts(override_dict, base_dict)
+                logger.debug("merged config dict", merged_dict=merged_dict)
+            except yaml.YAMLError as e:
+                raise InvalidConfigurationError(
+                    f"Error parsing override configuration file {override_config_path}: {e}"
+                ) from e
 
-    merged_dict = base_dict
-    if override_config_path and override_config_path.exists():
-        logger.info(
-            "using override config file", override_config_path=override_config_path
-        )
         try:
-            # We can't use load_config_from_file here because we expect
-            # the override config to not be a fully validated PlanarConfig object,
-            # and we need to merge it onto the base default config.
-            with open(override_config_path, "r") as f:
-                override_yaml_str = f.read()
-
-            # Expand environment variables in the YAML string
-            processed_yaml_str = os.path.expandvars(override_yaml_str)
-            logger.debug(
-                "processed override yaml string", processed_yaml_str=processed_yaml_str
-            )
-
-            override_dict = yaml.safe_load(processed_yaml_str) or {}
-            logger.debug("loaded override config", override_dict=override_dict)
-
-            # Deep merge the override onto the base dictionary
-            merged_dict = deep_merge_dicts(override_dict, base_dict)
-            logger.debug("merged config dict", merged_dict=merged_dict)
-        except yaml.YAMLError as e:
+            final_config = PlanarConfig.model_validate(merged_dict)
+            return final_config
+        except ValidationError as e:
             raise InvalidConfigurationError(
-                f"Error parsing override configuration file {override_config_path}: {e}"
+                f"Configuration validation error: {e}"
             ) from e
-
-    try:
-        final_config = PlanarConfig.model_validate(merged_dict)
-        return final_config
-    except ValidationError as e:
-        raise InvalidConfigurationError(f"Configuration validation error: {e}") from e

planar/data/__init__.py

@@ -6,6 +6,7 @@ lazy_exports(
     __name__,
     {
         "PlanarDataset": (".dataset", "PlanarDataset"),
+        "reset_connection_cache": (".connection", "reset_connection_cache"),
     },
 )
 

planar/data/config.py

@@ -2,7 +2,7 @@
 
 from typing import Annotated, Literal
 
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, ConfigDict, Field
 
 from planar.files.storage.config import StorageConfig
 
@@ -13,6 +13,8 @@ class DuckDBCatalogConfig(BaseModel):
     type: Literal["duckdb"]
     path: str  # Path to .ducklake file
 
+    model_config = ConfigDict(frozen=True)
+
 
 class PostgresCatalogConfig(BaseModel):
     """Configuration for PostgreSQL catalog backend."""
@@ -24,6 +26,8 @@ class PostgresCatalogConfig(BaseModel):
     password: str | None = None
     db: str
 
+    model_config = ConfigDict(frozen=True)
+
 
 class SQLiteCatalogConfig(BaseModel):
     """Configuration for SQLite catalog backend."""
@@ -31,6 +35,8 @@ class SQLiteCatalogConfig(BaseModel):
     type: Literal["sqlite"]
     path: str  # Path to .sqlite file
 
+    model_config = ConfigDict(frozen=True)
+
 
 # Discriminated union for catalog configurations
 CatalogConfig = Annotated[
@@ -47,3 +53,8 @@ class DataConfig(BaseModel):
 
     # Optional settings
     catalog_name: str = "planar_data"  # Default catalog name in Ducklake
+
+    model_config = ConfigDict(frozen=True)
+
+    def is_sqlite_catalog(self) -> bool:
+        return self.catalog.type == "sqlite"