plexspaces 0.1.4__tar.gz → 0.1.6__tar.gz

{plexspaces-0.1.4 → plexspaces-0.1.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plexspaces
-Version: 0.1.4
+Version: 0.1.6
 Summary: PlexSpaces Python SDK - Build actors with minimal boilerplate
 Author: PlexSpaces Contributors
 License: AGPL-3.0-or-later

{plexspaces-0.1.4 → plexspaces-0.1.6}/plexspaces/__init__.py

@@ -51,6 +51,7 @@ from .decorators import (
     signal_handler,
     query_handler,
 )
+from .agent import AgentLoop, AgentConfig, AgentTrajectory, AgentStep, AgentStepKind
 from .host import host, pg_first, ServiceHttpClient
 from .workflow import default_retry_config, with_retry
 from .leader_worker import LeaderWorkerClient, list_worker_node_ids
@@ -59,6 +60,11 @@ from .actor_id import ActorID
 __all__ = [
     "ActorID",
     "actor",
+    "AgentConfig",
+    "AgentLoop",
+    "AgentStep",
+    "AgentStepKind",
+    "AgentTrajectory",
     "default_retry_config",
     "event_actor",
     "gen_server_actor",

plexspaces-0.1.6/plexspaces/agent.py

@@ -0,0 +1,407 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2025 PlexSpaces Contributors
+#
+# This file is part of PlexSpaces.
+#
+# PlexSpaces is free software: you can redistribute it and/or modify it under
+# the terms of the GNU Affero General Public License as published by the Free
+# Software Foundation, either version 3 of the License, or (at your option)
+# any later version.
+#
+# PlexSpaces is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+# FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
+# details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with PlexSpaces. If not, see <https://www.gnu.org/licenses/>.
+
+"""
+Agent harness utilities for PlexSpaces Python SDK.
+
+``AgentLoop`` is a **standalone class** (no decorator magic, no class injection)
+that provides structured OODA step tracking, token budget enforcement, and
+suspend/resume helpers.  Use it with ``@workflow_actor`` for durable agent
+execution.
+
+Example::
+
+    from plexspaces import workflow_actor, state, run_handler, host
+    from plexspaces.agent import AgentLoop, AgentConfig
+
+    @workflow_actor
+    class ResearchAgent:
+        task: str = state(default="")
+
+        @run_handler
+        def run(self, task: str = "") -> dict:
+            loop = AgentLoop(
+                actor_id=host.actor_id(),
+                config=AgentConfig(max_iterations=10, token_budget=4096),
+            )
+            while not loop.iteration_limit_reached() and not loop.budget_exceeded():
+                obs    = loop.observe({"task": task})
+                plan   = loop.orient(obs)
+                action = loop.decide(plan)
+                result = loop.act(action)
+                loop.increment_iteration()
+                if result.get("done"):
+                    break
+            return loop.finalize_trajectory("completed", "task done")
+"""
+
+from __future__ import annotations
+
+import time
+import uuid
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional
+
+
+# ---------------------------------------------------------------------------
+# Utilities
+# ---------------------------------------------------------------------------
+
+def _now_ms() -> int:
+    """Current time as integer milliseconds since the Unix epoch."""
+    return int(time.time() * 1000)
+
+
+def _new_ulid() -> str:
+    """Generate a new ULID-compatible unique string (UUID4 fallback)."""
+    return str(uuid.uuid4())
+
+
+# ---------------------------------------------------------------------------
+# AgentStepKind constants
+# ---------------------------------------------------------------------------
+
+class AgentStepKind:
+    OBSERVE = "observe"
+    ORIENT = "orient"
+    DECIDE = "decide"
+    ACT = "act"
+    TOOL_CALL = "tool_call"
+    SUSPEND = "suspend"
+
+
+# ---------------------------------------------------------------------------
+# AgentStep
+# ---------------------------------------------------------------------------
+
+class AgentStep:
+    """A single step in an agent's OODA trajectory."""
+
+    def __init__(self, kind: str, method: str, input_data: Any = None):
+        self.step_id: str = _new_ulid()
+        self.kind: str = kind
+        self.method: str = method
+        self.input: Any = input_data
+        self.output: Any = None
+        self.started_at_ms: int = _now_ms()
+        self.completed_at_ms: Optional[int] = None
+        self.success: bool = False
+        self.error: Optional[str] = None
+        self.input_tokens: int = 0
+        self.output_tokens: int = 0
+        self.model: str = ""
+        self.metadata: Dict[str, str] = {}
+
+    def complete(
+        self,
+        output: Any,
+        input_tokens: int = 0,
+        output_tokens: int = 0,
+        model: str = "",
+    ) -> "AgentStep":
+        """Mark the step as successfully completed."""
+        self.output = output
+        self.completed_at_ms = _now_ms()
+        self.success = True
+        self.input_tokens = input_tokens
+        self.output_tokens = output_tokens
+        self.model = model
+        return self
+
+    def fail(self, error: str) -> "AgentStep":
+        """Mark the step as failed."""
+        self.completed_at_ms = _now_ms()
+        self.success = False
+        self.error = error
+        return self
+
+    @property
+    def duration_ms(self) -> int:
+        end = self.completed_at_ms or _now_ms()
+        return max(0, end - self.started_at_ms)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "step_id": self.step_id,
+            "kind": self.kind,
+            "method": self.method,
+            "input": self.input,
+            "output": self.output,
+            "started_at_ms": self.started_at_ms,
+            "completed_at_ms": self.completed_at_ms,
+            "duration_ms": self.duration_ms,
+            "success": self.success,
+            "error": self.error,
+            "input_tokens": self.input_tokens,
+            "output_tokens": self.output_tokens,
+            "model": self.model,
+            "metadata": self.metadata,
+        }
+
+
+# ---------------------------------------------------------------------------
+# AgentTrajectory
+# ---------------------------------------------------------------------------
+
+class AgentTrajectory:
+    """Complete trajectory for one agent run (all OODA steps, token totals)."""
+
+    def __init__(
+        self,
+        agent_actor_id: str,
+        eval_run_id: str = "",
+        scenario_id: str = "",
+    ):
+        self.trajectory_id: str = _new_ulid()
+        self.agent_actor_id: str = agent_actor_id
+        self.eval_run_id: str = eval_run_id
+        self.scenario_id: str = scenario_id
+        self.steps: List[AgentStep] = []
+        self.outcome: str = ""
+        self.outcome_detail: str = ""
+        self.started_at_ms: int = _now_ms()
+        self.completed_at_ms: Optional[int] = None
+        self.total_input_tokens: int = 0
+        self.total_output_tokens: int = 0
+
+    @property
+    def duration_ms(self) -> int:
+        end = self.completed_at_ms or _now_ms()
+        return max(0, end - self.started_at_ms)
+
+    @property
+    def step_count(self) -> int:
+        return len(self.steps)
+
+    def add_step(self, step: AgentStep) -> None:
+        """Append a completed step and accumulate token totals."""
+        self.steps.append(step)
+        self.total_input_tokens += step.input_tokens
+        self.total_output_tokens += step.output_tokens
+
+    def complete(self, outcome: str, detail: str = "") -> None:
+        """Finalise the trajectory with an outcome string."""
+        self.outcome = outcome
+        self.outcome_detail = detail
+        self.completed_at_ms = _now_ms()
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "trajectory_id": self.trajectory_id,
+            "agent_actor_id": self.agent_actor_id,
+            "eval_run_id": self.eval_run_id,
+            "scenario_id": self.scenario_id,
+            "steps": [s.to_dict() for s in self.steps],
+            "step_count": len(self.steps),
+            "outcome": self.outcome,
+            "outcome_detail": self.outcome_detail,
+            "started_at_ms": self.started_at_ms,
+            "completed_at_ms": self.completed_at_ms,
+            "duration_ms": self.duration_ms,
+            "total_input_tokens": self.total_input_tokens,
+            "total_output_tokens": self.total_output_tokens,
+        }
+
+
+# ---------------------------------------------------------------------------
+# AgentConfig
+# ---------------------------------------------------------------------------
+
+@dataclass
+class AgentConfig:
+    """Configuration for an AgentLoop."""
+    max_iterations: int = 10
+    token_budget: int = 0          # 0 = no budget limit
+
+
+# ---------------------------------------------------------------------------
+# AgentLoop
+# ---------------------------------------------------------------------------
+
+class AgentLoop:
+    """
+    Standalone agent harness utility.
+
+    Records OODA steps, enforces token budget and iteration limits, and
+    produces an ``AgentTrajectory`` on finalisation.
+
+    This is a **plain class** — there is no class injection or metaclass magic.
+    Use it inside a ``@workflow_actor`` ``run_handler``.
+
+    :param actor_id: ID of the hosting actor.
+    :param config:   Optional ``AgentConfig`` (max_iterations, token_budget).
+    :param eval_run_id: Optional eval run ID to tag the trajectory.
+    :param scenario_id: Optional scenario ID to tag the trajectory.
+    """
+
+    def __init__(
+        self,
+        actor_id: str,
+        config: Optional[AgentConfig] = None,
+        eval_run_id: str = "",
+        scenario_id: str = "",
+    ):
+        self._actor_id = actor_id
+        self._config = config or AgentConfig()
+        self._trajectory = AgentTrajectory(
+            agent_actor_id=actor_id,
+            eval_run_id=eval_run_id,
+            scenario_id=scenario_id,
+        )
+        self._iteration_count: int = 0
+        self.is_suspended: bool = False
+
+    # ── Private helpers ──────────────────────────────────────────────────────
+
+    def _record(
+        self,
+        kind: str,
+        input_data: Any,
+        output: Any = None,
+        input_tokens: int = 0,
+        output_tokens: int = 0,
+        model: str = "",
+        error: Optional[str] = None,
+    ) -> AgentStep:
+        started = _now_ms()
+        step = AgentStep(kind=kind, method=kind, input_data=input_data)
+        step.started_at_ms = started
+        if error:
+            step.fail(error)
+        else:
+            step.complete(
+                output=output,
+                input_tokens=input_tokens,
+                output_tokens=output_tokens,
+                model=model,
+            )
+        self._trajectory.add_step(step)
+        return step
+
+    # ── OODA step methods ─────────────────────────────────────────────────────
+
+    def observe(self, input_data: Any, **kwargs: Any) -> Any:
+        """Record an OBSERVE step.  Returns *input_data* unchanged."""
+        self._record(AgentStepKind.OBSERVE, input_data, output=input_data, **kwargs)
+        return input_data
+
+    def orient(self, input_data: Any, **kwargs: Any) -> Any:
+        """Record an ORIENT step.  Returns *input_data* unchanged."""
+        self._record(AgentStepKind.ORIENT, input_data, output=input_data, **kwargs)
+        return input_data
+
+    def decide(self, input_data: Any, **kwargs: Any) -> Any:
+        """Record a DECIDE step.  Returns *input_data* unchanged."""
+        self._record(AgentStepKind.DECIDE, input_data, output=input_data, **kwargs)
+        return input_data
+
+    def act(
+        self,
+        input_data: Any,
+        output: Any = None,
+        input_tokens: int = 0,
+        output_tokens: int = 0,
+        model: str = "",
+        **kwargs: Any,
+    ) -> Any:
+        """Record an ACT step.  Returns *output* (or *input_data* if output is None)."""
+        result = output if output is not None else input_data
+        self._record(
+            AgentStepKind.ACT,
+            input_data,
+            output=result,
+            input_tokens=input_tokens,
+            output_tokens=output_tokens,
+            model=model,
+        )
+        return result
+
+    def tool_call(
+        self,
+        name: str,
+        args: Any,
+        result: Any,
+        started_at_ms: Optional[int] = None,
+        input_tokens: int = 0,
+        output_tokens: int = 0,
+        model: str = "",
+    ) -> Any:
+        """Record a TOOL_CALL step.  Returns *result*."""
+        step = AgentStep(
+            kind=AgentStepKind.TOOL_CALL,
+            method=name,
+            input_data=args,
+        )
+        if started_at_ms is not None:
+            step.started_at_ms = started_at_ms
+        step.complete(
+            output=result,
+            input_tokens=input_tokens,
+            output_tokens=output_tokens,
+            model=model,
+        )
+        self._trajectory.add_step(step)
+        return result
+
+    # ── Control ───────────────────────────────────────────────────────────────
+
+    def suspend(self, reason: str) -> None:
+        """Mark the agent as suspended (waiting for external signal)."""
+        self.is_suspended = True
+        self._record(AgentStepKind.SUSPEND, reason)
+
+    def increment_iteration(self) -> None:
+        """Increment the OODA cycle counter.  Call once per full OODA cycle."""
+        self._iteration_count += 1
+
+    def budget_exceeded(self) -> bool:
+        """True if the cumulative token count meets or exceeds the budget."""
+        budget = self._config.token_budget
+        if budget <= 0:
+            return False
+        total = (
+            self._trajectory.total_input_tokens
+            + self._trajectory.total_output_tokens
+        )
+        return total >= budget
+
+    def iteration_limit_reached(self) -> bool:
+        """True if the OODA cycle count meets or exceeds max_iterations.
+
+        Returns False when max_iterations is 0 (unlimited), matching Go/TS/Rust.
+        """
+        if self._config.max_iterations <= 0:
+            return False
+        return self._iteration_count >= self._config.max_iterations
+
+    # ── Trajectory accessors ──────────────────────────────────────────────────
+
+    def get_trajectory(self) -> AgentTrajectory:
+        """Return the in-progress ``AgentTrajectory`` object."""
+        return self._trajectory
+
+    def finalize_trajectory(self, outcome: str, detail: str = "") -> Dict[str, Any]:
+        """
+        Finalise the trajectory with an outcome and return it as a dict.
+
+        :param outcome: "completed", "error", "timeout", "budget_exceeded", etc.
+        :param detail:  Human-readable detail.
+        :returns: ``AgentTrajectory.to_dict()``
+        """
+        self._trajectory.complete(outcome=outcome, detail=detail)
+        return self._trajectory.to_dict()

{plexspaces-0.1.4 → plexspaces-0.1.6}/plexspaces/generated/plexspaces/actor/v1/__init__.py

@@ -607,8 +607,8 @@ class Actor(betterproto.Message):
     
      ## Migration Strategy
      ```
-     Version 1 → 2: Add new field with default value (backward compatible, no migration)
-     Version 2 → 3: Remove deprecated field (backward compatible, no migration)
+     Version 1 → 2: Add new field with default value (no migration needed)
+     Version 2 → 3: Remove field (no migration needed)
      Version 3 → 4: Change field type (BREAKING - requires explicit migration function)
      Version 4 → 5: Restructure nested fields (BREAKING - requires migration)
      ```
@@ -771,7 +771,7 @@ class ActorConfig(betterproto.Message):
      // Version 1: Simple timeout config
      properties: {"timeout_ms": 5000}
     
-     // Version 2: Added retry config (backward compatible)
+     // Version 2: Added retry config
      properties: {
          "timeout_ms": 5000,
          "max_retries": 3,      // NEW: defaults to 3

{plexspaces-0.1.4 → plexspaces-0.1.6}/plexspaces/generated/plexspaces/metrics/v1/__init__.py

@@ -278,8 +278,7 @@ class ActorMetrics(betterproto.Message):
 
      ## Purpose
      Tracks actor lifecycle and message routing/delivery metrics that can be updated by ActorRegistry
-     without depending on Node. These metrics are also synced to NodeMetrics
-     via NodeMetricsUpdater for backward compatibility.
+     without depending on Node. These metrics are also synced to NodeMetrics via NodeMetricsUpdater.
 
      ## Design
      Proto-first design: All actor/message metrics are defined in proto for:

{plexspaces-0.1.4 → plexspaces-0.1.6}/plexspaces/generated/plexspaces/node/v1/__init__.py

@@ -1,5 +1,5 @@
 # Generated by the protocol buffer compiler.  DO NOT EDIT!
-# sources: plexspaces/v1/node/node.proto, plexspaces/v1/node/outbound.proto, plexspaces/v1/node/release.proto, plexspaces/v1/node/types.proto
+# sources: plexspaces/v1/node/node.proto, plexspaces/v1/node/outbound.proto, plexspaces/v1/node/release.proto
 # plugin: python-betterproto
 # This file has been @generated
 
@@ -148,93 +148,6 @@ class MemberState(betterproto.Enum):
     LEFT = 4
 
 
-class ShutdownErrorCode(betterproto.Enum):
-    """Shutdown coordinator error codes"""
-
-    SHUTDOWN_ERROR_UNSPECIFIED = 0
-    SHUTDOWN_ERROR_PHASE_FAILED = 1
-    """A shutdown phase failed (phase name + error in message)"""
-
-    SHUTDOWN_ERROR_TIMEOUT = 2
-    """Shutdown sequence timed out"""
-
-    SHUTDOWN_ERROR_OTHER = 3
-    """Other shutdown error"""
-
-
-class HealthCheckErrorCode(betterproto.Enum):
-    """Health check error codes"""
-
-    HEALTH_CHECK_ERROR_UNSPECIFIED = 0
-    HEALTH_CHECK_ERROR_CHECK_FAILED = 1
-    """A health check returned a failure result"""
-
-    HEALTH_CHECK_ERROR_TIMEOUT = 2
-    """Health check did not complete within deadline"""
-
-    HEALTH_CHECK_ERROR_OTHER = 3
-    """Unexpected error running a health check"""
-
-
-class BackgroundSchedulerErrorCode(betterproto.Enum):
-    """Background scheduler error codes"""
-
-    BACKGROUND_SCHEDULER_ERROR_UNSPECIFIED = 0
-    BACKGROUND_SCHEDULER_ERROR_ALREADY_STARTED = 1
-    """Scheduler already running for this node in the current process"""
-
-    BACKGROUND_SCHEDULER_ERROR_LOCK_ERROR = 2
-    """Lock manager error (lease acquisition)"""
-
-    BACKGROUND_SCHEDULER_ERROR_CHANNEL_ERROR = 3
-    """Internal channel error"""
-
-    BACKGROUND_SCHEDULER_ERROR_STATE_STORE_ERROR = 4
-    """State store error"""
-
-    BACKGROUND_SCHEDULER_ERROR_NODE_SELECTION_ERROR = 5
-    """Node selection error during scheduling"""
-
-
-class CapacityTrackerErrorCode(betterproto.Enum):
-    """Capacity tracker error codes"""
-
-    CAPACITY_TRACKER_ERROR_UNSPECIFIED = 0
-    CAPACITY_TRACKER_ERROR_REGISTRY_ERROR = 1
-    """ObjectRegistry error reading capacity data"""
-
-    CAPACITY_TRACKER_ERROR_INVALID_DATA = 2
-    """Capacity data is malformed or out of range"""
-
-
-class NodeSelectionErrorCode(betterproto.Enum):
-    """Node selection error codes"""
-
-    NODE_SELECTION_ERROR_UNSPECIFIED = 0
-    NODE_SELECTION_ERROR_NO_MATCHING_NODE = 1
-    """No node matched the resource requirements"""
-
-    NODE_SELECTION_ERROR_INVALID_REQUIREMENTS = 2
-    """Resource requirements are invalid or contradictory"""
-
-
-class TaskRouterErrorCode(betterproto.Enum):
-    """Task router error codes"""
-
-    TASK_ROUTER_ERROR_UNSPECIFIED = 0
-    TASK_ROUTER_ERROR_GROUP_NOT_FOUND = 1
-    """Shard group not found"""
-
-    TASK_ROUTER_ERROR_NO_ACTORS_IN_GROUP = 2
-    """Shard group has no actors registered"""
-
-    TASK_ROUTER_ERROR_CHANNEL_ERROR = 3
-    """Internal channel error"""
-
-    TASK_ROUTER_ERROR_INVALID_STRATEGY = 4
-    """Routing strategy is not valid for this request"""
-
-
 @dataclass(eq=False, repr=False)
 class HttpRetryPolicy(betterproto.Message):
     """
@@ -979,6 +892,15 @@ class SecurityConfig(betterproto.Message):
      Never use in production - always keep auth enabled.
     """
 
+    oidc: "__security_v1__.OidcConfig" = betterproto.message_field(6)
+    """
+    OIDC/OAuth2 configuration for dashboard UI login.
+    
+     Only active when disable_auth = false. In non-auth mode everyone is admin.
+     Supports any OIDC-compliant provider (Google, GitHub, Okta, Auth0, etc.)
+     Client secret should be set via PLEXSPACES_OIDC_CLIENT_SECRET env var.
+    """
+
 
 @dataclass(eq=False, repr=False)
 class ApplicationConfig(betterproto.Message):