synth-ai 0.2.9.dev11__py3-none-any.whl → 0.4.1__py3-none-any.whl

synth_ai/cli/local/session/constants.py

@@ -0,0 +1,63 @@
+"""Constants for agent session usage tracking.
+
+Shared constants used by both SDK and backend.
+"""
+
+from __future__ import annotations
+
+# Session status values
+SESSION_STATUS_ACTIVE = "active"  # Currently active session (only one per org/user)
+SESSION_STATUS_ENDED = "ended"
+SESSION_STATUS_LIMIT_EXCEEDED = "limit_exceeded"
+SESSION_STATUS_EXPIRED = "expired"
+
+# Limit types
+LIMIT_TYPE_HARD = "hard"
+LIMIT_TYPE_SOFT = "soft"
+LIMIT_TYPE_ROLLING_WINDOW = "rolling_window"
+
+# Metric types
+METRIC_TYPE_TOKENS = "tokens"
+METRIC_TYPE_COST_USD = "cost_usd"
+METRIC_TYPE_GPU_HOURS = "gpu_hours"
+METRIC_TYPE_API_CALLS = "api_calls"
+
+# Session types
+SESSION_TYPE_API_CALL = "api_call"
+SESSION_TYPE_JOB = "job"
+SESSION_TYPE_TRACING_SESSION = "tracing_session"
+
+# Reference types for usage records
+REFERENCE_TYPE_WALL_CLOCK_EVENT = "wall_clock_event"
+REFERENCE_TYPE_LLM_CALL = "llm_call"
+REFERENCE_TYPE_API_CALL = "api_call"
+REFERENCE_TYPE_CUSTOM = "custom"
+
+# Valid values sets (for validation)
+VALID_SESSION_STATUSES = {
+    SESSION_STATUS_ACTIVE,
+    SESSION_STATUS_ENDED,
+    SESSION_STATUS_LIMIT_EXCEEDED,
+    SESSION_STATUS_EXPIRED,
+}
+
+VALID_LIMIT_TYPES = {
+    LIMIT_TYPE_HARD,
+    LIMIT_TYPE_SOFT,
+    LIMIT_TYPE_ROLLING_WINDOW,
+}
+
+VALID_METRIC_TYPES = {
+    METRIC_TYPE_TOKENS,
+    METRIC_TYPE_COST_USD,
+    METRIC_TYPE_GPU_HOURS,
+    METRIC_TYPE_API_CALLS,
+}
+
+VALID_REFERENCE_TYPES = {
+    REFERENCE_TYPE_WALL_CLOCK_EVENT,
+    REFERENCE_TYPE_LLM_CALL,
+    REFERENCE_TYPE_API_CALL,
+    REFERENCE_TYPE_CUSTOM,
+}
+

synth_ai/cli/local/session/exceptions.py

@@ -0,0 +1,105 @@
+"""Shared exceptions for agent session usage tracking.
+
+These exceptions are used by both the SDK (synth-ai) and backend (monorepo).
+"""
+
+from __future__ import annotations
+
+from decimal import Decimal
+
+
+class SessionUsageError(Exception):
+    """Base exception for session usage errors."""
+
+    pass
+
+
+class LimitExceededError(SessionUsageError):
+    """Raised when a session limit is exceeded."""
+
+    def __init__(
+        self,
+        session_id: str,
+        metric_type: str,
+        limit_value: Decimal,
+        current_usage: Decimal,
+        attempted_usage: Decimal,
+        reason: str | None = None,
+    ):
+        self.session_id = session_id
+        self.metric_type = metric_type
+        self.limit_value = limit_value
+        self.current_usage = current_usage
+        self.attempted_usage = attempted_usage
+        self.reason = reason or "Hard limit exceeded"
+        
+        # Format metric type for display
+        metric_display = {
+            "cost_usd": "cost",
+            "gpu_hours": "GPU hours",
+            "api_calls": "API calls",
+        }.get(metric_type, metric_type)
+        
+        # Calculate what would have been the new total
+        projected_total = current_usage + attempted_usage
+        remaining = limit_value - current_usage
+        
+        message = (
+            f"Session '{session_id}' {metric_display} limit exceeded. "
+            f"Limit: {limit_value}, Current usage: {current_usage}, "
+            f"Attempted: {attempted_usage} (would be {projected_total} total). "
+            f"Remaining budget: {remaining}. "
+            f"To continue, end this session and create a new one with a higher limit, "
+            f"or increase the limit using client.increase_limit()"
+        )
+        super().__init__(message)
+
+
+class SessionNotFoundError(SessionUsageError):
+    """Raised when a session is not found."""
+
+    def __init__(self, session_id: str):
+        self.session_id = session_id
+        message = (
+            f"Session '{session_id}' not found. "
+            f"This session may have been deleted, or you may not have access to it. "
+            f"Verify the session ID is correct and belongs to your organization. "
+            f"List your sessions using client.list()"
+        )
+        super().__init__(message)
+
+
+class SessionNotActiveError(SessionUsageError):
+    """Raised when attempting to use an inactive session."""
+
+    def __init__(self, session_id: str, status: str):
+        self.session_id = session_id
+        self.status = status
+        
+        status_messages = {
+            "ended": "has been ended",
+            "limit_exceeded": "has exceeded its limit",
+            "expired": "has expired",
+        }
+        status_desc = status_messages.get(status, f"has status '{status}'")
+        
+        message = (
+            f"Session '{session_id}' is not active - it {status_desc}. "
+            f"To use this session, you must create a new active session using client.create()"
+        )
+        super().__init__(message)
+
+
+class InvalidLimitError(SessionUsageError):
+    """Raised when limit configuration is invalid."""
+
+    def __init__(self, message: str):
+        self.message = message
+        full_message = (
+            f"Invalid limit configuration: {message}. "
+            f"Valid limit types: 'hard', 'soft', 'rolling_window'. "
+            f"Valid metric types: 'tokens', 'cost_usd', 'gpu_hours', 'api_calls'. "
+            f"Limit value must be positive (> 0)."
+        )
+        super().__init__(full_message)
+

synth_ai/cli/local/session/manager.py

@@ -0,0 +1,139 @@
+"""High-level AgentSession manager for SDK."""
+
+from __future__ import annotations
+
+from contextlib import asynccontextmanager
+from datetime import datetime
+from decimal import Decimal
+from typing import Any, Optional
+from uuid import UUID
+
+from .client import AgentSessionClient
+from .exceptions import LimitExceededError, SessionNotFoundError
+from .models import AgentSession
+
+
+class AgentSessionManager:
+    """High-level manager for agent sessions.
+
+    Provides convenient methods for common operations and context managers
+    for automatic session lifecycle management.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str,
+        org_id: Optional[UUID] = None,
+        default_limits: Optional[list[dict[str, Any]]] = None,
+    ):
+        self.client = AgentSessionClient(base_url, api_key)
+        self.org_id = org_id
+        self.default_limits = default_limits or []
+        self._current_session: Optional[AgentSession] = None
+
+    @asynccontextmanager
+    async def session(
+        self,
+        session_id: Optional[str] = None,
+        limits: Optional[list[dict[str, Any]]] = None,
+        tracing_session_id: Optional[str] = None,
+        expires_at: Optional[datetime] = None,
+        metadata: Optional[dict[str, Any]] = None,
+        auto_end: bool = True,
+    ):
+        """Context manager for agent session lifecycle.
+
+        Example:
+            async with manager.session(limits=[...]) as session:
+                # Use session.session_id in API calls
+                await manager.record_usage(session.session_id, ...)
+        """
+        if not self.org_id:
+            raise ValueError(
+                "org_id is required for session creation. "
+                "Either provide org_id explicitly, or ensure the client can fetch it from /api/v1/me endpoint."
+            )
+
+        limits = limits or self.default_limits
+        session = await self.client.create(
+            org_id=self.org_id,
+            limits=limits,
+            tracing_session_id=tracing_session_id,
+            expires_at=expires_at,
+            metadata=metadata,
+            session_id=session_id,
+        )
+
+        self._current_session = session
+        try:
+            yield session
+        finally:
+            if auto_end:
+                await self.client.end(session.session_id)
+            self._current_session = None
+
+    async def ensure_session(
+        self,
+        session_id: Optional[str] = None,
+    ) -> AgentSession:
+        """Get existing session or create new one.
+
+        Useful for CLI where session might already exist.
+        """
+        if session_id:
+            try:
+                return await self.client.get(session_id)
+            except SessionNotFoundError:
+                pass
+
+        # Create new session
+        if not self.org_id:
+            raise ValueError(
+                "org_id is required for session creation. "
+                "Either provide org_id explicitly, or ensure the client can fetch it from /api/v1/me endpoint."
+            )
+
+        return await self.client.create(
+            org_id=self.org_id,
+            limits=self.default_limits,
+        )
+
+    @property
+    def current_session(self) -> Optional[AgentSession]:
+        """Get current active session (if any)."""
+        return self._current_session
+
+    async def check_and_record(
+        self,
+        session_id: str,
+        metric_type: str,
+        estimated_value: Decimal,
+        actual_value: Decimal,
+        reference_type: Optional[str] = None,
+        reference_id: Optional[str] = None,
+    ) -> None:
+        """Check limit, record usage, handle errors.
+
+        Convenience method that:
+        1. Checks limit with estimated value
+        2. Records actual usage (if limit check endpoint exists)
+        3. Raises LimitExceededError if limit hit
+
+        Note: Actual usage recording would need to be implemented via API endpoint.
+        """
+        # Check limit
+        check = await self.client.check_limit(session_id, metric_type, estimated_value)
+        if not check.allowed:
+            raise LimitExceededError(
+                session_id=session_id,
+                metric_type=metric_type,
+                limit_value=check.limit_value,
+                current_usage=check.current_usage,
+                attempted_usage=estimated_value,
+                reason=check.reason,
+            )
+
+        # Note: Usage recording would need an API endpoint
+        # For now, this is a placeholder
+

synth_ai/cli/local/session/models.py

@@ -0,0 +1,89 @@
+"""Agent session data models for SDK."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from decimal import Decimal
+from typing import Any, Optional
+from uuid import UUID
+
+
+@dataclass
+class AgentSessionLimit:
+    """Limit configuration for an agent session."""
+
+    limit_type: str  # 'hard', 'soft', 'rolling_window'
+    metric_type: str  # 'tokens', 'cost_usd', 'gpu_hours', 'api_calls'
+    limit_value: Decimal
+    current_usage: Decimal = Decimal("0")
+    warning_threshold: Optional[Decimal] = None
+    window_seconds: Optional[int] = None
+    limit_id: Optional[UUID] = None
+    exceeded_at: Optional[datetime] = None
+    exceeded_reason: Optional[str] = None
+    created_at: Optional[datetime] = None
+    expires_at: Optional[datetime] = None
+
+    @property
+    def remaining(self) -> Decimal:
+        """Calculate remaining limit."""
+        return self.limit_value - self.current_usage
+
+
+@dataclass
+class AgentSessionUsage:
+    """Current usage summary for a session."""
+
+    tokens: Decimal = Decimal("0")
+    cost_usd: Decimal = Decimal("0")
+    gpu_hours: Decimal = Decimal("0")
+    api_calls: int = 0
+
+
+@dataclass
+class LimitCheckResult:
+    """Result of a limit check."""
+
+    allowed: bool
+    limit_value: Decimal
+    current_usage: Decimal
+    remaining: Decimal
+    reason: Optional[str] = None
+
+
+@dataclass
+class AgentSession:
+    """Agent session representation."""
+
+    session_id: str
+    org_id: UUID
+    created_at: datetime
+    user_id: Optional[UUID] = None
+    api_key_id: Optional[UUID] = None
+    expires_at: Optional[datetime] = None
+    ended_at: Optional[datetime] = None
+    status: str = "active"  # 'active', 'ended', 'limit_exceeded', 'expired'
+    limit_exceeded_reason: Optional[str] = None
+    usage: AgentSessionUsage = field(default_factory=AgentSessionUsage)
+    limits: list[AgentSessionLimit] = field(default_factory=list)
+    tracing_session_id: Optional[str] = None
+    session_type: str = "api_call"  # 'api_call', 'job', 'tracing_session'
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class SessionUsageRecord:
+    """Individual usage event within a session."""
+
+    id: UUID
+    session_id: str
+    metric_type: str
+    metric_value: Decimal
+    org_id: UUID
+    created_at: datetime
+    reference_type: Optional[str] = None
+    reference_id: Optional[str] = None
+    user_id: Optional[UUID] = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+

synth_ai/cli/local/session/query.py

@@ -0,0 +1,110 @@
+"""Query builder for agent sessions (SDK)."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Optional
+from uuid import UUID
+
+from .client import AgentSessionClient
+from .models import AgentSession
+
+
+class AgentSessionQuery:
+    """Fluent query builder for agent sessions."""
+
+    def __init__(self, client: AgentSessionClient):
+        self._client = client
+        self._filters: dict[str, Any] = {}
+        self._order_by: Optional[str] = None
+        self._limit: Optional[int] = None
+        self._offset: int = 0
+
+    def org_id(self, org_id: UUID) -> AgentSessionQuery:
+        """Filter by organization ID."""
+        self._filters["org_id"] = org_id
+        return self
+
+    def user_id(self, user_id: UUID) -> AgentSessionQuery:
+        """Filter by user ID."""
+        self._filters["user_id"] = user_id
+        return self
+
+    def status(self, status: str) -> AgentSessionQuery:
+        """Filter by status."""
+        self._filters["status"] = status
+        return self
+
+    def created_after(self, after: datetime) -> AgentSessionQuery:
+        """Filter sessions created after date."""
+        self._filters["created_after"] = after
+        return self
+
+    def created_before(self, before: datetime) -> AgentSessionQuery:
+        """Filter sessions created before date."""
+        self._filters["created_before"] = before
+        return self
+
+    def has_limit_exceeded(self) -> AgentSessionQuery:
+        """Filter sessions that exceeded limits."""
+        self._filters["limit_exceeded"] = True
+        return self
+
+    def tracing_session_id(self, tracing_session_id: str) -> AgentSessionQuery:
+        """Filter by tracing session ID."""
+        self._filters["tracing_session_id"] = tracing_session_id
+        return self
+
+    def order_by(self, field: str, desc: bool = True) -> AgentSessionQuery:
+        """Order results."""
+        self._order_by = f"{field} {'DESC' if desc else 'ASC'}"
+        return self
+
+    def limit(self, limit: int) -> AgentSessionQuery:
+        """Limit number of results."""
+        self._limit = limit
+        return self
+
+    def offset(self, offset: int) -> AgentSessionQuery:
+        """Offset for pagination."""
+        self._offset = offset
+        return self
+
+    async def execute(self) -> list[AgentSession]:
+        """Execute query and return results."""
+        params: dict[str, Any] = {}
+        
+        if "org_id" in self._filters:
+            # org_id is implicit from API key, so we don't need to pass it
+            pass
+        if "user_id" in self._filters:
+            params["user_id"] = str(self._filters["user_id"])
+        if "status" in self._filters:
+            params["status"] = self._filters["status"]
+        if "created_after" in self._filters:
+            params["created_after"] = self._filters["created_after"].isoformat()
+        if "created_before" in self._filters:
+            params["created_before"] = self._filters["created_before"].isoformat()
+        if "limit_exceeded" in self._filters and self._filters["limit_exceeded"]:
+            params["status"] = "limit_exceeded"
+        if "tracing_session_id" in self._filters:
+            params["tracing_session_id"] = self._filters["tracing_session_id"]
+        
+        if self._limit:
+            params["limit"] = self._limit
+        if self._offset:
+            params["offset"] = self._offset
+        
+        # Use client's list method
+        return await self._client.list(**params)
+
+    async def count(self) -> int:
+        """Get count of matching sessions."""
+        results = await self.execute()
+        return len(results)
+
+    async def first(self) -> Optional[AgentSession]:
+        """Get first matching session."""
+        results = await self.limit(1).execute()
+        return results[0] if results else None
+

synth_ai/cli/root.py

@@ -18,6 +18,21 @@ import time
 
 import click
 
+# Set RUST_LOG to suppress noisy codex_otel logs by default
+# This suppresses verbose SSE event logs from Cursor's Rust logging
+if "RUST_LOG" not in os.environ:
+    os.environ["RUST_LOG"] = "codex_otel::otel_event_manager=warn"
+
+# Install log filter early to suppress noisy codex_otel logs
+try:
+    from synth_ai.core.log_filter import install_log_filter
+    
+    # Only install if not already filtered (to avoid double-wrapping)
+    install_log_filter()
+except Exception:
+    # Silently fail if log filter can't be installed
+    pass
+
 try:
     from importlib.metadata import PackageNotFoundError
     from importlib.metadata import version as _pkg_version
@@ -149,113 +164,21 @@ def install_sqld() -> str:
 
 
 @click.group(
-    help=f"Synth AI v{__pkg_version__} - Software for aiding the best and multiplying the will."
+    help=f"Synth AI v{__pkg_version__}"
 )
 @click.version_option(version=__pkg_version__, prog_name="synth-ai")
 def cli():
     """Top-level command group for Synth AI."""
-
-
-# === Legacy demo command group (aliases new rl_demo implementation) ===
-@cli.group()
-def demo():
-    """Demo helpers (deploy, configure, run)."""
-
-
-def _forward_to_demo(args: list[str]) -> None:
-    # Lazy import to avoid loading demo deps unless needed
-    try:
-        from synth_ai.demos.core import cli as demo_cli  # type: ignore
-    except Exception as e:  # pragma: no cover
-        click.echo(f"Failed to import demo CLI: {e}")
-        sys.exit(1)
-    rc = int(demo_cli.main(args) or 0)  # type: ignore[attr-defined]
-    if rc != 0:
-        sys.exit(rc)
-
-
-# (prepare command removed; handled by configure)
-
-
-@demo.command()
-@click.option("--local", is_flag=True, help="Run local FastAPI instead of Modal deploy")
-@click.option(
-    "--app", type=click.Path(), default=None, help="Path to Modal app.py for uv run modal deploy"
-)
-@click.option("--name", type=str, default="synth-math-demo", help="Modal app name")
-@click.option(
-    "--script", type=click.Path(), default=None, help="Path to deploy_task_app.sh (optional legacy)"
-)
-def deploy(local: bool, app: str | None, name: str, script: str | None):
-    """Deploy the Math Task App (Modal by default)."""
-    args: list[str] = ["rl_demo.deploy"]
-    if local:
-        args.append("--local")
-    if app:
-        args.extend(["--app", app])
-    if name:
-        args.extend(["--name", name])
-    if script:
-        args.extend(["--script", script])
-    _forward_to_demo(args)
-
-
-@demo.command()
-def configure():
-    """Print resolved environment and config path."""
-    _forward_to_demo(["rl_demo.configure"])
-
-
-@demo.command()
-def setup():
-    """Perform SDK handshake and write keys to .env."""
-    _forward_to_demo(["rl_demo.setup"])
-
-
-@demo.command()
-@click.option("--template", type=str, default=None, help="Template id to instantiate")
-@click.option("--dest", type=str, default=None, help="Destination directory for files")
-@click.option("--force", is_flag=True, help="Overwrite existing files in destination")
-def init(template: str | None, dest: str | None, force: bool):
-    """Copy demo task app template into the current directory."""
-    args: list[str] = ["demo.init"]
-    if template:
-        args.extend(["--template", template])
-    if dest:
-        args.extend(["--dest", dest])
-    if force:
-        args.append("--force")
-    _forward_to_demo(args)
-
-
-@demo.command()
-@click.option("--batch-size", type=int, default=None)
-@click.option("--group-size", type=int, default=None)
-@click.option("--model", type=str, default=None)
-@click.option("--timeout", type=int, default=600)
-def run(batch_size: int | None, group_size: int | None, model: str | None, timeout: int):
-    """Kick off a short RL job using the prepared TOML."""
-    args = ["rl_demo.run"]
-    if batch_size is not None:
-        args.extend(["--batch-size", str(batch_size)])
-    if group_size is not None:
-        args.extend(["--group-size", str(group_size)])
-    if model:
-        args.extend(["--model", model])
-    if timeout:
-        args.extend(["--timeout", str(timeout)])
-    _forward_to_demo(args)
-
-
-@cli.command(name="setup")
-def setup_command():
-    """Perform SDK handshake and write keys to .env."""
-    _forward_to_demo(["rl_demo.setup"])
+    # Add logging to track CLI invocation
+    import sys
+    if "train" in sys.argv:
+        sys.stderr.write(f"[CLI_ROOT] CLI invoked with args: {sys.argv}\n")
+        sys.stderr.flush()
 
 
 @cli.command()
 @click.option("--db-file", default="traces/v3/synth_ai.db", help="Database file path")
-@click.option("--sqld-port", default=8080, type=int, help="Port for sqld HTTP interface")
+@click.option("--sqld-port", default=8080, type=int, help="Port for sqld Hrana WebSocket interface (HTTP API will be port+1)")
 @click.option("--env-port", default=8901, type=int, help="Port for environment service")
 @click.option("--no-sqld", is_flag=True, help="Skip starting sqld daemon")
 @click.option("--no-env", is_flag=True, help="Skip starting environment service")
@@ -301,21 +224,25 @@ def serve_deprecated(
 
     if not no_sqld:
         try:
+            hrana_port = sqld_port
+            http_port = sqld_port + 1
             result = subprocess.run(
-                ["pgrep", "-f", f"sqld.*--http-listen-addr.*:{sqld_port}"],
+                ["pgrep", "-f", f"sqld.*(--hrana-listen-addr.*:{hrana_port}|--http-listen-addr.*:{http_port})"],
                 capture_output=True,
                 text=True,
             )
             if result.returncode != 0:
                 sqld_bin = find_sqld_binary() or install_sqld()
-                click.echo(f"🗄️  Starting sqld (local only) on port {sqld_port}")
+                click.echo(f"🗄️  Starting sqld (local only) on hrana port {hrana_port}, HTTP API port {http_port}")
                 proc = subprocess.Popen(
                     [
                         sqld_bin,
                         "--db-path",
                         db_file,
+                        "--hrana-listen-addr",
+                        f"127.0.0.1:{hrana_port}",
                         "--http-listen-addr",
-                        f"127.0.0.1:{sqld_port}",
+                        f"127.0.0.1:{http_port}",
                     ],
                     stdout=open("sqld.log", "w"),  # noqa: SIM115
                     stderr=subprocess.STDOUT,
@@ -371,7 +298,7 @@ def serve_deprecated(
         click.echo(f"   Working directory: {os.getcwd()}")
         click.echo("")
         click.echo("🔄 Starting services...")
-        click.echo(f"   - sqld daemon: http://127.0.0.1:{sqld_port}")
+        click.echo(f"   - sqld daemon: libsql://127.0.0.1:{sqld_port} (HTTP API: http://127.0.0.1:{sqld_port + 1})")
         click.echo(f"   - Environment service: http://127.0.0.1:{env_port}")
         click.echo("")
         click.echo("💡 Tips:")