polos-sdk 0.1.0__py3-none-any.whl → 0.1.2__py3-none-any.whl

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/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/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/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/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/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/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/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/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:

polos_sdk-0.1.2.dist-info/METADATA

@@ -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.0.dist-info → polos_sdk-0.1.2.dist-info}/RECORD

@@ -1,16 +1,16 @@
 polos/__init__.py,sha256=WTVHY01DfbioRF7A130k7SLizsC9UJZoySmz9lJ_VnA,2402
 polos/agents/__init__.py,sha256=z6Pyyzbd8fKf2oA49hQ_1srj0nyCrS8XsuWAMYExz3c,122
-polos/agents/agent.py,sha256=Y1JZvhqrEoirwbMvP948G-95iWB4kJAv9qBswmXGxP8,26426
+polos/agents/agent.py,sha256=f3nXltSr28M9_sFaxndHjFx6NhO5bD5kqLTyEpu0vVQ,26592
 polos/agents/conversation_history.py,sha256=W4efQU4p7yyMAkAw8jFkA9YEkQn-7giZKr0lkyBUJ-w,3918
 polos/agents/stop_conditions.py,sha256=2qV27F4J8SfOHDZ3iGqUUELuBLmLIK08Fj7WOapo8cQ,9456
-polos/agents/stream.py,sha256=d6L2e7RmmN275tuAcugFiqRq7snUndgXoPGSoCBMR6g,25127
+polos/agents/stream.py,sha256=XHF6N2od1DCVLHZlpdwRBgMwf_7Kv8rvSbg8k4wtyg0,25819
 polos/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 polos/core/context.py,sha256=vkwM4cQ93p1-K_muT6obxYV_dzgsPDOC3HT-OKNF6jE,5053
 polos/core/state.py,sha256=MKWaGM1kLQEw0Q2VWD-PXB3CkK1tiqoTmeoQRwIpngg,774
-polos/core/step.py,sha256=6uZcbbyk_zo7sR76PVw_9hXdgfpRyf5veDsoQwJcKrk,51700
-polos/core/workflow.py,sha256=xGGNye2bb5B7W2RWsVFmYb5fz8349sGeAWZXjJgUuD0,51093
+polos/core/step.py,sha256=BmSMXyPYVnoLEOz4TDyJgslFg0jLFmy_Ey6keN1MIwI,52116
+polos/core/workflow.py,sha256=VNxTUObkdtjxftGaeUF7hSpcr-rYioO2-cQva7L2tYs,51524
 polos/features/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-polos/features/events.py,sha256=7viS9ryCeEnOaAO4blsLH45ulBPknDa9ISfif0jmhig,14237
+polos/features/events.py,sha256=8Ixel43iRe2rHB6bdLMMpYt5qy_jxDpfOmL7saVa0Fg,14145
 polos/features/schedules.py,sha256=SpnQLOHKShZJA-Hteoqto5eTiq3Sin4-y8-K2RTQouw,3077
 polos/features/tracing.py,sha256=xOaj9WLqK7B9IwRUDyCDVZ7IGhVPDxQ1YB1UQ3aFK2w,22736
 polos/features/wait.py,sha256=c2NUz1BPG56EGIdxQwuDhydnyztqD5B9KBTlaimdofE,2504
@@ -33,12 +33,12 @@ polos/middleware/hook.py,sha256=qhzjQP5I6DkL4GbdIrauDTesUQh067whyt1PxbP8qH8,4780
 polos/middleware/hook_executor.py,sha256=732Kw89deLjDZPJyKQ0ZDlmOinp7dksBZenBdPSkpfg,3669
 polos/runtime/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 polos/runtime/batch.py,sha256=hrzHi2oP5jJ6SJemESnkWI22v3m_GIMgh38fOscmM8k,2879
-polos/runtime/client.py,sha256=iiJOU4zeNHHv61uzWNO7TablP4IQFPWcROMXRoSaQd0,32984
+polos/runtime/client.py,sha256=52N2l86V7z91RYrE4glMC83yhZRKkrZxsK79PEA24ME,33257
 polos/runtime/queue.py,sha256=QeLgCVnMemchj7FdT_K5zsy-86iNTOqf2Wm3s1Cg-lA,1257
-polos/runtime/worker.py,sha256=5KF0IgknIFNDhnZiFx2m7MLUXysgmt_np-1dI5euFf0,56398
+polos/runtime/worker.py,sha256=Eo6HeJPSY0dpfUZ6U261oNDgK2guaNET53LoTtWE04U,56459
 polos/runtime/worker_server.py,sha256=HtWCyufL184R-aAIU_p0vVhwlWH4PDseQjZ2qPKpEns,10120
 polos/tools/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-polos/tools/tool.py,sha256=OmaNBCQgA8e5uRJTO88pNR3eP1BDQiK2jvxkrPYdrag,22483
+polos/tools/tool.py,sha256=6MMTjPmc-j6ihjO-oQUpM2yDvFiagoOnDL--HI7Xliw,22542
 polos/types/__init__.py,sha256=Va3Yg1JbuDIzXFt5czG2hrN7DZL19k04DNBguUf-JlA,360
 polos/types/types.py,sha256=wqYKLqm8nZ2Ba5BEDJpMgS88XzzeGV9zzX_ntGP8lpw,2919
 polos/utils/__init__.py,sha256=E9PPg23MCxh-82TlQeD4-VNo0gQo3rJDQxaw7EVbVfo,636
@@ -47,9 +47,9 @@ polos/utils/client_context.py,sha256=drSXD_4zPwn83KaNbp3B7vQcDH9IUbni1hT7TSG2DGU
 polos/utils/config.py,sha256=VXfccQgtVTX5ieFnHosB8xqcoHecDT2hJ09rJMnKvWw,399
 polos/utils/output_schema.py,sha256=wJSZviqPCcqWrDfUlBFHCKYmuOqNZTqw4hYhqGZFI10,14235
 polos/utils/retry.py,sha256=Igz4degC0IUWnsJsRKVIrkNjYm57DG467EcLbmMOMuM,1398
-polos/utils/serializer.py,sha256=5BvdBSXPKGwO0F3FubiXV8vuMyW3AC1-4Jwz3Bc7eik,5486
+polos/utils/serializer.py,sha256=XfnZ7vIbTk_xly116De1xJiNncJdb1GIjAERys7ZV10,6554
 polos/utils/tracing.py,sha256=SkBktU12KyIQcl8q1wjyTX7QfGwyzdzEcBY8QTX_t6Y,1021
 polos/utils/worker_singleton.py,sha256=7-MOx9VFlyC-8waB7OMg6xER5NB7Ld7ofMku9yoitDo,1081
-polos_sdk-0.1.0.dist-info/METADATA,sha256=66gs2_-Sk0xinDRF7KD6pR8JfY8Q0I2zmOijV_aibFQ,16924
-polos_sdk-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-polos_sdk-0.1.0.dist-info/RECORD,,
+polos_sdk-0.1.2.dist-info/METADATA,sha256=whWoDVWW56tKr819JhVzi6lhOvd4jF4MI2te01_7U-M,3870
+polos_sdk-0.1.2.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+polos_sdk-0.1.2.dist-info/RECORD,,

polos_sdk-0.1.0.dist-info/METADATA

@@ -1,650 +0,0 @@
-Metadata-Version: 2.4
-Name: polos-sdk
-Version: 0.1.0
-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
-- 🔒 **Isolated Execution** - Each workflow runs in a secure environment
-
-## Installation
-
-```bash
-pip install polos-worker
-```
-
-Or with UV (recommended):
-```bash
-uv add polos-worker
-```
-
-### Optional Dependencies
-
-Install provider-specific dependencies for LLM support:
-
-```bash
-# OpenAI
-pip install polos-worker[openai]
-
-# Anthropic
-pip install polos-worker[anthropic]
-
-# Google Gemini
-pip install polos-worker[gemini]
-
-# Groq
-pip install polos-worker[groq]
-
-# Fireworks
-pip install polos-worker[fireworks]
-
-# Together AI
-pip install polos-worker[together]
-
-# All providers
-pip install polos-worker[openai,anthropic,gemini,groq,fireworks,together]
-```
-
-## Quick Start
-
-### 1. Configure the SDK
-
-```python
-from polos import configure
-
-configure(
-    api_url='http://localhost:8080',
-    api_key='your-api-key',  # Optional if running in dev mode
-    project_id='your-project-id'
-)
-```
-
-Or use environment variables:
-```bash
-export POLOS_API_URL=http://localhost:8080
-export POLOS_API_KEY=your-api-key
-export POLOS_PROJECT_ID=your-project-id
-```
-
-### 2. Define a Workflow
-
-```python
-from polos import workflow, WorkflowContext
-
-@workflow(id="hello_world")
-async def hello_world(ctx: WorkflowContext, payload: dict):
-    """A simple workflow."""
-    name = payload.get('name', 'World')
-    return {'message': f'Hello, {name}!'}
-```
-
-### 3. Create an Agent
-
-```python
-from polos import Agent
-
-weather_agent = Agent(
-    id="weather-agent",
-    provider="openai",
-    model="gpt-5-mini",
-    system_prompt="You are a helpful weather assistant",
-    tools=[get_weather]  # Your custom tools
-)
-```
-
-### 4. Run Your Code
-
-Start a worker to execute workflows and agents:
-
-```bash
-# Using the Python worker
-python -m polos.runtime.worker
-
-# Or use the Node.js worker (supports Python workflows)
-npm install -g polos-worker
-polos-worker start
-```
-
-## Core Concepts
-
-### Workflows
-
-Workflows are durable functions that can survive failures and resume execution:
-
-```python
-from polos import workflow, WorkflowContext, WorkflowState
-
-class MyState(WorkflowState):
-    counter: int = 0
-    messages: list[str] = []
-
-@workflow(id="my_workflow", state_schema=MyState)
-async def my_workflow(ctx: WorkflowContext, payload: dict):
-    # Access state
-    ctx.state.counter += 1
-    ctx.state.messages.append(payload.get('message', ''))
-    
-    # Use step.run() for durable execution
-    result = await ctx.step.run("process_data", process_data, payload)
-    
-    return {'result': result, 'counter': ctx.state.counter}
-```
-
-### Agents
-
-Agents are LLM-powered workflows with tool calling capabilities:
-
-```python
-from polos import Agent, max_steps, executed_tool
-
-# Define a tool
-from polos import tool
-
-@tool
-def get_weather(ctx, location: str) -> str:
-    """Get weather for a location."""
-    # Your weather API call here
-    return f"Weather in {location}: 72°F, sunny"
-
-# Create an agent
-weather_agent = Agent(
-    id="weather-agent",
-    provider="openai",
-    model="gpt-5-mini",
-    system_prompt="You are a helpful weather assistant",
-    tools=[get_weather],
-    stop_conditions=[max_steps(10), executed_tool("get_weather")]
-)
-
-# Use the agent
-result = await weather_agent.run("What's the weather in NYC?")
-print(result.result)  # Agent's response
-
-# Or stream the response
-stream_result = await weather_agent.stream("What's the weather in NYC?")
-async for event in stream_result.events:
-    if event.event_type == "text_delta":
-        print(event.data.get("content", ""), end="", flush=True)
-```
-
-### Tools
-
-Tools are functions that agents can call:
-
-```python
-from polos import tool, WorkflowContext
-
-@tool
-def calculate(ctx: WorkflowContext, expression: str) -> float:
-    """Evaluate a mathematical expression."""
-    return eval(expression)  # In production, use a safe evaluator
-
-@tool
-def search_web(ctx: WorkflowContext, query: str) -> str:
-    """Search the web for information."""
-    # Your search implementation
-    return f"Results for: {query}"
-```
-
-### Hooks
-
-Hooks allow you to intercept workflow execution:
-
-```python
-from polos import hook, HookContext, HookResult, HookAction
-
-@hook
-def log_execution(ctx: WorkflowContext, hook_ctx: HookContext) -> HookResult:
-    """Log workflow execution."""
-    print(f"Workflow {ctx.workflow_id} started")
-    return HookResult.continue_with()
-
-@workflow(id="my_workflow", on_start=log_execution)
-async def my_workflow(ctx: WorkflowContext, payload: dict):
-    return {'result': 'done'}
-```
-
-### Guardrails
-
-Guardrails validate and modify agent outputs:
-
-```python
-from polos import guardrail, GuardrailContext, GuardrailResult
-
-@guardrail
-def check_profanity(ctx: GuardrailContext) -> GuardrailResult:
-    """Check for profanity in agent output."""
-    content = ctx.content or ""
-    if any(word in content.lower() for word in ["bad", "word"]):
-        return GuardrailResult.fail("Content contains inappropriate language")
-    return GuardrailResult.continue_with()
-
-weather_agent = Agent(
-    id="weather-agent",
-    provider="openai",
-    model="gpt-5-mini",
-    guardrails=[check_profanity]
-)
-```
-
-## Advanced Features
-
-### State Management
-
-Workflows can maintain state across executions:
-
-```python
-from polos import workflow, WorkflowContext, WorkflowState
-
-class CounterState(WorkflowState):
-    count: int = 0
-    history: list[str] = []
-
-@workflow(id="counter", state_schema=CounterState)
-async def counter(ctx: WorkflowContext, payload: dict):
-    ctx.state.count += 1
-    ctx.state.history.append(payload.get('action', ''))
-    return {'count': ctx.state.count}
-```
-
-### Step Execution
-
-Use `ctx.step` for durable execution:
-
-```python
-@workflow(id="my_workflow")
-async def my_workflow(ctx: WorkflowContext, payload: dict):
-    # Run a step (durable)
-    result = await ctx.step.run("step_name", my_function, arg1, arg2)
-    
-    # Invoke another workflow and wait
-    result = await ctx.step.invoke_and_wait("other_workflow", other_workflow, payload)
-    
-    # Invoke another workflow (fire and forget)
-    handle = await ctx.step.invoke("other_workflow", other_workflow, payload)
-    
-    # Wait for a workflow to complete
-    result = await ctx.step.wait_for(handle)
-    
-    return result
-```
-
-### Events
-
-Publish and subscribe to events:
-
-```python
-from polos import events
-
-# Publish an event
-await events.publish(
-    topic="user/123",
-    event_type="message",
-    data={"text": "Hello"}
-)
-
-# Stream events
-async for event in events.stream_topic("user/123"):
-    print(f"Event: {event.event_type} - {event.data}")
-```
-
-### Scheduled Workflows
-
-Schedule workflows to run on a schedule:
-
-```python
-@workflow(
-    id="daily_report",
-    schedule="0 9 * * *"  # 9 AM daily
-)
-async def daily_report(ctx: WorkflowContext, payload: dict):
-    # Generate daily report
-    return {'report': '...'}
-```
-
-### Queues
-
-Use queues for concurrency control:
-
-```python
-from polos import Queue
-
-my_queue = Queue(name="processing", concurrency_limit=5)
-
-@workflow(id="processor", queue=my_queue)
-async def processor(ctx: WorkflowContext, payload: dict):
-    # Process item
-    return {'status': 'processed'}
-```
-
-### Batch Execution
-
-Execute workflows in batch:
-
-```python
-from polos import batch
-
-results = await batch.run(
-    workflow_id="my_workflow",
-    inputs=[
-        {"value": 1},
-        {"value": 2},
-        {"value": 3}
-    ]
-)
-
-for result in results:
-    print(result.result)
-```
-
-## Testing
-
-The SDK includes comprehensive unit tests. Run tests with:
-
-```bash
-# Install test dependencies
-uv sync --dev
-
-# Run all tests
-uv run pytest
-
-# Run with coverage
-uv run pytest --cov=polos --cov-report=html
-
-# Run specific test file
-uv run pytest tests/unit/test_core/test_workflow.py
-```
-
-See [`TESTING_PLAN.md`](./TESTING_PLAN.md) for testing guidelines.
-
-## Development Setup
-
-### Using UV (Recommended)
-
-```bash
-# Fork the repository on GitHub first: https://github.com/polos-dev/polos
-# Then clone your fork
-git clone https://github.com/YOUR_USERNAME/polos.git
-cd polos/sdk/python
-
-# Install dependencies (creates venv automatically)
-uv sync
-
-# Format code with Ruff
-uv run ruff format .
-
-# Lint code
-uv run ruff check .
-
-# Run tests
-uv run pytest
-
-# Build package
-uv build
-```
-
-### Using pip
-
-```bash
-# Create virtual environment
-python -m venv venv
-source venv/bin/activate  # Windows: venv\Scripts\activate
-
-# Install in development mode
-pip install -e ".[dev]"
-
-# Format code
-ruff format .
-
-# Lint code
-ruff check .
-
-# Run tests
-pytest
-```
-
-### Pre-commit Hooks
-
-The project uses pre-commit hooks for code quality:
-
-```bash
-# Install pre-commit
-pip install pre-commit
-
-# Install hooks
-pre-commit install
-
-# Run hooks manually
-pre-commit run --all-files
-```
-
-## Project Structure
-
-```
-sdk/python/
-├── polos/                  # Main package
-│   ├── agents/             # Agent implementation
-│   ├── core/               # Core workflow/step/context
-│   ├── features/           # Events, schedules, tracing
-│   ├── llm/                # LLM providers
-│   ├── middleware/         # Hooks and guardrails
-│   ├── runtime/            # Worker and client
-│   ├── tools/              # Tool implementation
-│   ├── types/              # Type definitions
-│   └── utils/              # Utility functions
-├── tests/                  # Test suite
-│   └── unit/               # Unit tests
-├── pyproject.toml          # Project configuration
-└── README.md               # This file
-```
-
-## API Reference
-
-### Core Functions
-
-#### `@workflow(id, queue, schedule, state_schema, ...)`
-
-Decorator to register a workflow function.
-
-**Parameters:**
-- `id` (str): Unique workflow identifier
-- `queue` (str | Queue | dict, optional): Queue configuration
-- `schedule` (str | dict, optional): Cron schedule or schedule config
-- `state_schema` (type[WorkflowState], optional): State schema class
-- `on_start` (Callable | list, optional): Hooks to run on start
-- `on_end` (Callable | list, optional): Hooks to run on end
-
-**Example:**
-```python
-@workflow(id="my_workflow", state_schema=MyState)
-async def my_workflow(ctx: WorkflowContext, payload: dict):
-    return {'result': 'done'}
-```
-
-#### `Agent(id, provider, model, ...)`
-
-Create an AI agent.
-
-**Parameters:**
-- `id` (str): Unique agent identifier
-- `provider` (str): LLM provider ("openai", "anthropic", etc.)
-- `model` (str): Model name (e.g., "gpt-4o", "claude-sonnet-4-5")
-- `system_prompt` (str, optional): System prompt
-- `tools` (list, optional): List of tools
-- `stop_conditions` (list, optional): Stop condition callables
-- `guardrails` (list, optional): Guardrail callables
-
-**Example:**
-```python
-agent = Agent(
-    id="my-agent",
-    provider="openai",
-    model="gpt-5-mini",
-    tools=[my_tool]
-)
-```
-
-#### `@tool`
-
-Decorator to register a tool function.
-
-**Example:**
-```python
-@tool
-def my_tool(ctx: WorkflowContext, arg: str) -> str:
-    return f"Processed: {arg}"
-```
-
-### Context Objects
-
-#### `WorkflowContext`
-
-Context object passed to workflow functions.
-
-**Properties:**
-- `workflow_id` (str): Workflow identifier
-- `execution_id` (str): Current execution ID
-- `root_execution_id` (str): Root execution ID
-- `state` (WorkflowState): Workflow state
-- `step` (Step): Step helper for durable execution
-
-#### `AgentContext`
-
-Context object passed to agent functions (extends `WorkflowContext`).
-
-**Additional Properties:**
-- `agent_id` (str): Agent identifier
-- `conversation_id` (str, optional): Conversation ID for history
-
-## Environment Variables
-
-- `POLOS_API_URL` - Orchestrator URL (default: `http://localhost:8080`)
-- `POLOS_API_KEY` - API key for authentication
-- `POLOS_PROJECT_ID` - Project ID for multi-project support
-
-## Architecture
-
-Polos uses a push-based worker architecture:
-
-```
-┌─────────────┐
-│   Client    │ ── trigger ──> ┌──────────────┐
-└─────────────┘                │ Orchestrator │
-                               │  (Rust API)  │
-                               └──────────────┘
-                                      │
-                                   invokes
-                                      ↓
-┌─────────────┐              ┌──────────────┐
-│  Executor   │ <── pushes ──│    Worker    │
-│  (Python)   │              │   (Python)   │
-└─────────────┘              └──────────────┘
-```
-
-1. **Client** triggers workflow/agent via SDK
-2. **Orchestrator** queues execution in database
-3. **Orchestrator** pushes execution to worker via HTTP
-4. **Worker** receives execution request and executes workflow/agent in process
-5. **Worker** reports result back to orchestrator
-6. **Orchestrator** marks execution complete
-7. **Client** receives result
-
-## Contributing
-
-We welcome contributions! See [CONTRIBUTING.md](../../CONTRIBUTING.md) for guidelines.
-
-### Development Workflow
-
-1. **Fork the repository** on GitHub: https://github.com/polos-dev/polos
-2. **Clone your fork**:
-   ```bash
-   git clone https://github.com/YOUR_USERNAME/polos.git
-   cd polos/sdk/python
-   ```
-3. **Add upstream remote** (optional, for syncing with main repo):
-   ```bash
-   git remote add upstream https://github.com/polos-dev/polos.git
-   ```
-4. Create a feature branch
-5. Make your changes
-6. Run tests: `uv run pytest`
-7. Format code: `uv run ruff format .`
-8. Lint code: `uv run ruff check .`
-9. Submit a pull request to `polos-dev/polos`
-
-## License
-
-MIT License - see [LICENSE](../../LICENSE) for details.
-
-## Support
-
-- 📖 [Documentation](https://docs.polos.dev)
-- 💬 [Discord Community](https://discord.gg/polos)
-- 🐛 [Issue Tracker](https://github.com/polos-dev/polos/issues)
-- 📧 [Email Support](mailto:support@polos.dev)
-
-## Related Projects
-
-- [Polos Orchestrator](../../orchestrator) - Rust-based orchestrator
-- [Polos UI](../../ui) - Web interface for monitoring and management
-
----
-
-Built with ❤️ by the Polos team