polos-sdk 0.1.0__tar.gz → 0.1.2__tar.gz

{polos_sdk-0.1.0 → polos_sdk-0.1.2}/BUILD.md

@@ -51,6 +51,23 @@ uv run ruff check .
 uv run ruff check --fix .
 ```
 
+#### Using uvx (Alternative)
+
+If `uv run` fails due to version detection issues (e.g., missing git tags), use `uvx` to run tools directly without building the package:
+
+```bash
+# Format code
+uvx ruff format .
+
+# Lint code
+uvx ruff check .
+
+# Auto-fix linting issues
+uvx ruff check --fix .
+```
+
+`uvx` runs the tool in an isolated environment without needing to install or build the SDK package.
+
 ## Building the Package
 
 ### Build Locally

polos_sdk-0.1.2/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: polos-sdk
+Version: 0.1.2
+Summary: Polos SDK for Python - Durable Agent Execution
+Project-URL: Homepage, https://github.com/polos-dev/polos
+Project-URL: Repository, https://github.com/polos-dev/polos
+Project-URL: Documentation, https://docs.polos.dev
+Project-URL: Issues, https://github.com/polos-dev/polos/issues
+Author: Polos Team
+License: Apache-2.0
+Keywords: agents,ai,async,durable-execution,llm,orchestration,workflow
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: anyio>=4.0.0
+Requires-Dist: fastapi>=0.104.0
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: opentelemetry-api>=1.20.0
+Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.20.0
+Requires-Dist: opentelemetry-sdk>=1.20.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: uvicorn>=0.24.0
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.39.0; extra == 'anthropic'
+Provides-Extra: dev
+Requires-Dist: pre-commit>=3.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest-mock>=3.10.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: fireworks
+Requires-Dist: openai>=1.0.0; extra == 'fireworks'
+Provides-Extra: gemini
+Requires-Dist: openai>=1.0.0; extra == 'gemini'
+Provides-Extra: groq
+Requires-Dist: openai>=1.0.0; extra == 'groq'
+Provides-Extra: openai
+Requires-Dist: openai>=1.0.0; extra == 'openai'
+Provides-Extra: together
+Requires-Dist: openai>=1.0.0; extra == 'together'
+Description-Content-Type: text/markdown
+
+# Polos Python SDK
+
+Durable execution engine for Python. Build reliable AI agents and workflows that can survive failures, handle long-running tasks, and coordinate complex processes.
+
+## Features
+
+- 🤖 **AI Agents** - Build LLM-powered agents with tool calling, streaming, and conversation history
+- 🔄 **Durable Workflows** - Workflows survive failures and resume from checkpoints
+- ⏰ **Long-Running** - Execute workflows that run for hours or days
+- 🔗 **Workflow Orchestration** - Chain workflows together and build complex processes
+- 🛠️ **Tools** - Define reusable tools that agents can call
+- 🐍 **Native Python** - Async/await support, type hints, and Pythonic APIs
+- 📊 **Observability** - Built-in tracing, events, and monitoring
+
+## Installation
+
+```bash
+pip install polos-sdk
+```
+
+Or with UV (recommended):
+```bash
+uv add polos-sdk
+```
+
+### Optional Dependencies
+
+Install provider-specific dependencies for LLM support:
+
+```bash
+# OpenAI
+pip install polos-sdk[openai]
+
+# Anthropic
+pip install polos-sdk[anthropic]
+
+# Google Gemini
+pip install polos-sdk[gemini]
+
+# Groq
+pip install polos-sdk[groq]
+
+# Fireworks
+pip install polos-sdk[fireworks]
+
+# Together AI
+pip install polos-sdk[together]
+
+# All providers
+pip install polos-sdk[openai,anthropic,gemini,groq,fireworks,together]
+```
+
+## Quick Start
+
+Use the quickstart guide at [https://docs.polos.dev](https://docs.polos.dev) to get started in minutes.
+
+## License
+
+Apache-2.0 - see [LICENSE](../../LICENSE) for details.
+
+## Support
+
+- 📖 [Documentation](https://docs.polos.dev)
+- 💬 [Discord Community](https://discord.gg/ZAxHKMPwFG)
+- 🐛 [Issue Tracker](https://github.com/polos-dev/polos/issues)
+- 📧 [Email Support](mailto:support@polos.dev)
+
+---
+
+Built with ❤️ by the Polos team

polos_sdk-0.1.2/README.md

@@ -0,0 +1,70 @@
+# Polos Python SDK
+
+Durable execution engine for Python. Build reliable AI agents and workflows that can survive failures, handle long-running tasks, and coordinate complex processes.
+
+## Features
+
+- 🤖 **AI Agents** - Build LLM-powered agents with tool calling, streaming, and conversation history
+- 🔄 **Durable Workflows** - Workflows survive failures and resume from checkpoints
+- ⏰ **Long-Running** - Execute workflows that run for hours or days
+- 🔗 **Workflow Orchestration** - Chain workflows together and build complex processes
+- 🛠️ **Tools** - Define reusable tools that agents can call
+- 🐍 **Native Python** - Async/await support, type hints, and Pythonic APIs
+- 📊 **Observability** - Built-in tracing, events, and monitoring
+
+## Installation
+
+```bash
+pip install polos-sdk
+```
+
+Or with UV (recommended):
+```bash
+uv add polos-sdk
+```
+
+### Optional Dependencies
+
+Install provider-specific dependencies for LLM support:
+
+```bash
+# OpenAI
+pip install polos-sdk[openai]
+
+# Anthropic
+pip install polos-sdk[anthropic]
+
+# Google Gemini
+pip install polos-sdk[gemini]
+
+# Groq
+pip install polos-sdk[groq]
+
+# Fireworks
+pip install polos-sdk[fireworks]
+
+# Together AI
+pip install polos-sdk[together]
+
+# All providers
+pip install polos-sdk[openai,anthropic,gemini,groq,fireworks,together]
+```
+
+## Quick Start
+
+Use the quickstart guide at [https://docs.polos.dev](https://docs.polos.dev) to get started in minutes.
+
+## License
+
+Apache-2.0 - see [LICENSE](../../LICENSE) for details.
+
+## Support
+
+- 📖 [Documentation](https://docs.polos.dev)
+- 💬 [Discord Community](https://discord.gg/ZAxHKMPwFG)
+- 🐛 [Issue Tracker](https://github.com/polos-dev/polos/issues)
+- 📧 [Email Support](mailto:support@polos.dev)
+
+---
+
+Built with ❤️ by the Polos team

{polos_sdk-0.1.0 → polos_sdk-0.1.2}/polos/agents/agent.py

@@ -351,6 +351,7 @@ class Agent(Workflow):
         id: str,  # Required: task ID
         provider: str,
         model: str,
+        description: str | None = None,  # Description for team coordination
         system_prompt: str | None = None,
         tools: list[Any] | None = None,
         temperature: float | None = None,
@@ -388,6 +389,7 @@ class Agent(Workflow):
         super().__init__(
             id=id,
             func=self._agent_execute,
+            description=description,
             workflow_type="agent",
             queue_name=queue_name,
             queue_concurrency_limit=queue_concurrency_limit,
@@ -689,6 +691,7 @@ class Agent(Workflow):
                 "input": input,
                 "session_id": session_id,
                 "user_id": user_id,
+                "conversation_id": conversation_id,
                 "streaming": True,
                 "provider_kwargs": kwargs,  # Pass kwargs to provider
             },

{polos_sdk-0.1.0 → polos_sdk-0.1.2}/polos/agents/stream.py

@@ -56,7 +56,6 @@ async def _agent_stream_function(ctx: AgentContext, payload: dict[str, Any]) ->
     agent_run_id = ctx.execution_id  # Use execution_id from context
     agent_config = payload["agent_config"]
     streaming = payload.get("streaming", True)  # Default to True for backward compatibility
-    tool_stop_action = False
     input_data = payload.get("input")
 
     result = {
@@ -206,6 +205,23 @@ async def _agent_stream_function(ctx: AgentContext, payload: dict[str, Any]) ->
                     "tool_results": tool_results,  # Tool results from previous iteration
                 },
             )
+
+            if guardrails and streaming and llm_result.get("content"):
+                # Emit one text_delta event with full response for clients who are streaming
+                await ctx.step.publish_event(
+                    f"llm_generate:text_delta:{agent_step}",
+                    topic=f"workflow:{agent_run_id}",
+                    event_type="text_delta",
+                    data={
+                        "step": agent_step,
+                        "chunk_index": 1,
+                        "content": llm_result.get("content"),
+                        "_metadata": {
+                            "execution_id": agent_run_id,
+                            "workflow_id": ctx.workflow_id,
+                        },
+                    },
+                )
         else:
             # No guardrails - use streaming
             llm_result = await _llm_stream(
@@ -313,7 +329,7 @@ async def _agent_stream_function(ctx: AgentContext, payload: dict[str, Any]) ->
             )
 
         # Execute all tools in batch
-        if tool_stop_action is False and len(batch_workflows) > 0:
+        if len(batch_workflows) > 0:
             tool_results_list: list[BatchStepResult] = await ctx.step.batch_invoke_and_wait(
                 f"execute_tools:step_{agent_step}", batch_workflows
             )
@@ -453,7 +469,7 @@ async def _agent_stream_function(ctx: AgentContext, payload: dict[str, Any]) ->
                 raise StepExecutionError(hook_result.error_message or "Hook execution failed")
 
         # No tool results, we're done
-        if tool_results is None or len(tool_results) == 0 or tool_stop_action:
+        if tool_results is None or len(tool_results) == 0:
             end_steps = True
 
         # Evaluate stop conditions (if any)

{polos_sdk-0.1.0 → polos_sdk-0.1.2}/polos/core/step.py

@@ -134,6 +134,13 @@ class Step:
             # Extract full module path for Pydantic class
             # (e.g., "polos.llm.providers.base.LLMResponse")
             output_schema_name = f"{result.__class__.__module__}.{result.__class__.__name__}"
+        elif isinstance(result, list) and result and isinstance(result[0], BaseModel):
+            # Handle list of Pydantic models
+            outputs = [item.model_dump(mode="json") for item in result]
+            # Store schema name of the list item type for deserialization
+            output_schema_name = (
+                f"list[{result[0].__class__.__module__}.{result[0].__class__.__name__}]"
+            )
         else:
             outputs = result
 

{polos_sdk-0.1.0 → polos_sdk-0.1.2}/polos/core/workflow.py

@@ -80,6 +80,7 @@ class Workflow:
         self,
         id: str,
         func: Callable,
+        description: str | None = None,  # Description for team coordination
         workflow_type: str | None = "workflow",
         queue_name: str | None = None,
         queue_concurrency_limit: int | None = None,
@@ -94,6 +95,7 @@ class Workflow:
         state_schema: type[BaseModel] | None = None,
     ):
         self.id = id
+        self.description = description  # Description for team coordination
         self.func = func
         self.is_async = asyncio.iscoroutinefunction(func)
         # Check if function has a payload parameter
@@ -849,6 +851,7 @@ class Workflow:
 
 def workflow(
     id: str | None = None,
+    description: str | None = None,  # Description for team coordination
     queue: str | Queue | dict[str, Any] | None = None,
     trigger_on_event: str | None = None,
     batch_size: int = 1,
@@ -938,6 +941,8 @@ def workflow(
 
     Args:
         id: Optional workflow ID (defaults to function name)
+        description: Optional description for team coordination. Used when this
+            workflow is added to a Team so the coordinator LLM understands its purpose.
         queue: Optional queue configuration. Can be:
             - str: Queue name
             - Queue: Queue object
@@ -1158,6 +1163,7 @@ def workflow(
         workflow_obj = Workflow(
             id=workflow_id,
             func=func,
+            description=description,
             queue_name=queue_name,
             queue_concurrency_limit=queue_concurrency_limit,
             trigger_on_event=trigger_on_event,

{polos_sdk-0.1.0 → polos_sdk-0.1.2}/polos/features/events.py

@@ -235,8 +235,7 @@ async def batch_publish(
 async def publish(
     client: PolosClient,
     topic: str,
-    event_type: str | None = None,
-    data: dict[str, Any] = None,
+    event_data: EventData,
     execution_id: str | None = None,
     root_execution_id: str | None = None,
 ) -> int:
@@ -247,20 +246,16 @@ async def publish(
     Args:
         client: PolosClient instance
         topic: Event topic
-        event_type: Optional type of event
-        data: Event payload
+        event_data: EventData
+        execution_id: Optional execution ID
+        root_execution_id: Optional root execution ID
 
     Returns:
         sequence_id: Global sequence ID for the event
     """
     sequence_ids = await batch_publish(
         topic=topic,
-        events=[
-            EventData(
-                event_type=event_type,
-                data=data or {},
-            )
-        ],
+        events=[event_data],
         execution_id=execution_id,
         root_execution_id=root_execution_id,
         client=client,

{polos_sdk-0.1.0 → polos_sdk-0.1.2}/polos/runtime/client.py

@@ -48,17 +48,22 @@ class PolosClient:
         api_url: str | None = None,
         api_key: str | None = None,
         project_id: str | None = None,
+        deployment_id: str | None = None,
     ):
         """Initialize Polos client.
 
         Args:
-            api_url: Orchestrator API URL (default: from POLOS_API_URL env var or http://localhost:8080)
+            api_url: Orchestrator API URL (default: from POLOS_API_URL env var or
+                http://localhost:8080)
             api_key: API key for authentication (default: from POLOS_API_KEY env var)
             project_id: Project ID for multi-tenancy (default: from POLOS_PROJECT_ID env var)
+            deployment_id: Deployment ID for workflow invocations (default: from
+                POLOS_DEPLOYMENT_ID env var, None uses latest deployment)
         """
         self.api_url = api_url or os.getenv("POLOS_API_URL", "http://localhost:8080")
         self.api_key = api_key or os.getenv("POLOS_API_KEY")
         self.project_id = project_id or os.getenv("POLOS_PROJECT_ID")
+        self.deployment_id = deployment_id or os.getenv("POLOS_DEPLOYMENT_ID")
 
         # Validate required fields (with local mode support)
         local_mode_requested = os.getenv("POLOS_LOCAL_MODE", "False").lower() == "true"
@@ -158,7 +163,6 @@ class PolosClient:
         Args:
             workflow_id: The workflow identifier
             payload: The workflow payload
-            deployment_id: Optional deployment ID (if not provided, uses latest active)
             queue_name: Optional queue name (if not provided, defaults to workflow_id)
             queue_concurrency_limit: Optional concurrency limit for queue creation
             concurrency_key: Optional concurrency key for per-tenant queuing
@@ -172,7 +176,7 @@ class PolosClient:
         """
         return await self._submit_workflow(
             workflow_id=workflow_id,
-            deployment_id=None,  # Use latest deployment
+            deployment_id=self.deployment_id,  # Use client's deployment_id (None uses latest)
             payload=payload,
             queue_name=queue_name,
             queue_concurrency_limit=queue_concurrency_limit,
@@ -235,7 +239,7 @@ class PolosClient:
         # Submit all workflows in a single batch using the batch endpoint
         handles = await self._submit_workflows(
             workflows=workflow_requests,
-            deployment_id=None,  # Use latest active deployment
+            deployment_id=self.deployment_id,  # Use client's deployment_id (None uses latest)
             parent_execution_id=None,
             root_execution_id=None,
             step_key=None,  # Not invoked from a step, so no step_key

{polos_sdk-0.1.0 → polos_sdk-0.1.2}/polos/runtime/worker.py

@@ -187,8 +187,8 @@ class Worker:
 
         # Build workflow registry
         self.workflows_registry: dict[str, Workflow] = {}
-        self.agents: list[Agent] = [a for a in agents if isinstance(a, Agent)] or []
-        self.tools: list[Tool] = [t for t in tools if isinstance(t, Tool)] or []
+        self.agents: list[Agent] = [a for a in (agents or []) if isinstance(a, Agent)] or []
+        self.tools: list[Tool] = [t for t in (tools or []) if isinstance(t, Tool)] or []
         self.agent_ids: list[str] = []
         self.tool_ids: list[str] = []
         self.workflow_ids: list[str] = []
@@ -938,7 +938,9 @@ class Worker:
             # Check if error is StepExecutionError - if so, mark as non-retryable
             # Tools are not retryable by default. We feed the error back to the LLM to handle.
             retryable = (
-                not isinstance(error, StepExecutionError) and workflow.workflow_type != "tool"
+                workflow
+                and not isinstance(error, StepExecutionError)
+                and workflow.workflow_type != "tool"
             )
             await self._report_failure(
                 workflow_data["execution_id"], error_message, stack_trace, retryable=retryable

{polos_sdk-0.1.0 → polos_sdk-0.1.2}/polos/tools/tool.py

@@ -63,6 +63,7 @@ class Tool(Workflow):
             id=id,
             func=func or self._default_execute,
             workflow_type="tool",
+            description=description or self.__doc__ or "",
             queue_name=queue_name,
             queue_concurrency_limit=queue_concurrency_limit,
             on_start=on_start,

{polos_sdk-0.1.0 → polos_sdk-0.1.2}/polos/utils/serializer.py

@@ -87,11 +87,31 @@ async def deserialize(obj: Any, output_schema_name: str | None = None) -> Any:
 
     Args:
         obj: Object to deserialize
-        output_schema_name: The name of the output schema
+        output_schema_name: The name of the output schema (can be
+            "list[module.ClassName]" for lists)
 
     Returns:
         Deserialized object
     """
+    # Handle list of Pydantic models (schema format: "list[module.ClassName]")
+    if output_schema_name and output_schema_name.startswith("list[") and isinstance(obj, list):
+        try:
+            # Extract the inner class name from "list[module.ClassName]"
+            inner_schema = output_schema_name[5:-1]  # Remove "list[" and "]"
+            module_path, class_name = inner_schema.rsplit(".", 1)
+            module = __import__(module_path, fromlist=[class_name])
+            model_class = getattr(module, class_name)
+
+            # Validate each item in the list back to the Pydantic model
+            if issubclass(model_class, BaseModel):
+                obj = [model_class.model_validate(item) for item in obj]
+        except (ImportError, AttributeError, ValueError, TypeError) as e:
+            raise Exception(
+                f"Failed to reconstruct Pydantic model list from output_schema_name: "
+                f"{output_schema_name}. Error: {str(e)}"
+            ) from e
+        return obj
+
     # If output_schema_name is present, try to reconstruct the Pydantic model
     if output_schema_name and isinstance(obj, dict):
         try: