sofias-sdk-lite 0.1.0__tar.gz

sofias_sdk_lite-0.1.0/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: sofias-sdk-lite
+Version: 0.1.0
+Summary: Build agents on the Sofias agent graph and run them over RabbitMQ.
+License-Expression: Apache-2.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: aio-pika>=9.0.0
+Requires-Dist: rstream>=1.0.0
+Requires-Dist: nh3>=0.3.6
+Requires-Dist: mkdocs-material>=9.5 ; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.25 ; extra == 'docs'
+Requires-Python: >=3.11
+Provides-Extra: docs
+Description-Content-Type: text/markdown
+
+# sofias-sdk-lite
+
+Build multi-node agents on a declarative graph and run them against RabbitMQ.
+
+`sofias-sdk-lite` gives you:
+
+- **An agent graph** — LLM nodes, function nodes, delegation nodes (agent-to-agent),
+  aggregator nodes (fan-in), and planner nodes (dynamic DAGs), wired together with
+  explicit routing strategies.
+- **A messaging layer** — pydantic wire models (`AgentTaskMessage`, `StreamFragment`,
+  delegation contracts) and a RabbitMQ transport (client, consumer, publisher, RPC,
+  delegation transport) built on `aio-pika` and RabbitMQ Streams.
+- **A runner** — `AgentRunner` consumes tasks from a queue, resolves per-request
+  settings, executes your agent, and streams the response back — with graceful
+  shutdown, retries, and circuit breakers built in.
+- **Bring your own LLM** — `LLMCallable` is a protocol. Wrap any HTTP client,
+  local model, or provider SDK in ~15 lines; no vendor lock-in.
+
+Nothing here depends on a private backend, an internal config service, or a
+specific LLM vendor. Everything infrastructure-specific is a constructor
+argument or a protocol you implement yourself.
+
+## Install
+
+```bash
+pip install sofias-sdk-lite
+# or
+uv add sofias-sdk-lite
+```
+
+Requires Python 3.11+ and a running RabbitMQ broker (with the
+[Streams plugin](https://www.rabbitmq.com/docs/streams) enabled) if you use
+the runner or streaming responses.
+
+## Quickstart
+
+A minimal agent with a single function node:
+
+```python
+import asyncio
+
+from sofias_sdk_lite import (
+    AgentBuilder,
+    AgentMessage,
+    BaseAgentSettings,
+    InputContract,
+    NodeContract,
+    OutputContract,
+)
+
+
+class GreetInput(InputContract):
+    name: str
+
+
+class GreetOutput(OutputContract):
+    greeting: str
+
+
+class HelloSettings(BaseAgentSettings):
+    pass
+
+
+def greet(data: dict, context: dict | None = None) -> dict:
+    return {"greeting": f"Hello, {data['name']}!"}
+
+
+async def main() -> None:
+    contract = NodeContract(input_schema=GreetInput, output_schema=GreetOutput)
+    agent = (
+        AgentBuilder("hello_agent", version="0.1.0")
+        .with_settings_class(HelloSettings)
+        .with_contract(input_schema=GreetInput, output_schema=GreetOutput)
+        .add_function_node("greeter", contract, process_fn=greet)
+        .set_entry_node("greeter")
+        .set_terminal("greeter")
+        .build()
+    )
+
+    response = await agent.execute(AgentMessage(content=GreetInput(name="World")))
+    print(response.content)  # {"greeting": "Hello, World!"}
+
+
+asyncio.run(main())
+```
+
+See [`examples/`](examples/) for a runner against a local RabbitMQ
+(`docker-compose.yml` included), tool loops, streaming, and agent-to-agent
+delegation.
+
+## Running an agent against RabbitMQ
+
+```python
+from sofias_sdk_lite import AgentRunner, RunnerConfig, RabbitMQConfig, AgentMessage
+
+
+class MyAgentRunner(AgentRunner):
+    settings_class = MySettings
+
+    def build_agent(self, settings, workflow):
+        return (
+            AgentBuilder("my_agent")
+            .with_settings_class(type(settings))
+            .with_response_workflow(workflow)
+            # ... nodes, routing ...
+            .build()
+        )
+
+    def prepare_input(self, task, history, role):
+        return AgentMessage(
+            content=MyInput(message=task.content, role=role),
+            conversation_id=task.conversation_id,
+        )
+
+
+if __name__ == "__main__":
+    MyAgentRunner(
+        RunnerConfig(
+            queue="my-agent-tasks",
+            agent_name="my_agent",
+            rabbitmq=RabbitMQConfig(host="localhost"),
+        )
+    ).run()
+```
+
+## Scope (v1)
+
+Core agent graph, RabbitMQ messaging, and the runner ship today. Memory,
+MCP tool discovery, and LLM adapter implementations are intentionally out
+of scope for v1 — the SDK ships the relevant protocols
+(`MemoryProvider`, `ToolProvider`, `LLMCallable`) so you can plug in your
+own, and these become optional extras in a later release.
+
+## License
+
+Apache-2.0. See [LICENSE](LICENSE).

sofias_sdk_lite-0.1.0/README.md

@@ -0,0 +1,136 @@
+# sofias-sdk-lite
+
+Build multi-node agents on a declarative graph and run them against RabbitMQ.
+
+`sofias-sdk-lite` gives you:
+
+- **An agent graph** — LLM nodes, function nodes, delegation nodes (agent-to-agent),
+  aggregator nodes (fan-in), and planner nodes (dynamic DAGs), wired together with
+  explicit routing strategies.
+- **A messaging layer** — pydantic wire models (`AgentTaskMessage`, `StreamFragment`,
+  delegation contracts) and a RabbitMQ transport (client, consumer, publisher, RPC,
+  delegation transport) built on `aio-pika` and RabbitMQ Streams.
+- **A runner** — `AgentRunner` consumes tasks from a queue, resolves per-request
+  settings, executes your agent, and streams the response back — with graceful
+  shutdown, retries, and circuit breakers built in.
+- **Bring your own LLM** — `LLMCallable` is a protocol. Wrap any HTTP client,
+  local model, or provider SDK in ~15 lines; no vendor lock-in.
+
+Nothing here depends on a private backend, an internal config service, or a
+specific LLM vendor. Everything infrastructure-specific is a constructor
+argument or a protocol you implement yourself.
+
+## Install
+
+```bash
+pip install sofias-sdk-lite
+# or
+uv add sofias-sdk-lite
+```
+
+Requires Python 3.11+ and a running RabbitMQ broker (with the
+[Streams plugin](https://www.rabbitmq.com/docs/streams) enabled) if you use
+the runner or streaming responses.
+
+## Quickstart
+
+A minimal agent with a single function node:
+
+```python
+import asyncio
+
+from sofias_sdk_lite import (
+    AgentBuilder,
+    AgentMessage,
+    BaseAgentSettings,
+    InputContract,
+    NodeContract,
+    OutputContract,
+)
+
+
+class GreetInput(InputContract):
+    name: str
+
+
+class GreetOutput(OutputContract):
+    greeting: str
+
+
+class HelloSettings(BaseAgentSettings):
+    pass
+
+
+def greet(data: dict, context: dict | None = None) -> dict:
+    return {"greeting": f"Hello, {data['name']}!"}
+
+
+async def main() -> None:
+    contract = NodeContract(input_schema=GreetInput, output_schema=GreetOutput)
+    agent = (
+        AgentBuilder("hello_agent", version="0.1.0")
+        .with_settings_class(HelloSettings)
+        .with_contract(input_schema=GreetInput, output_schema=GreetOutput)
+        .add_function_node("greeter", contract, process_fn=greet)
+        .set_entry_node("greeter")
+        .set_terminal("greeter")
+        .build()
+    )
+
+    response = await agent.execute(AgentMessage(content=GreetInput(name="World")))
+    print(response.content)  # {"greeting": "Hello, World!"}
+
+
+asyncio.run(main())
+```
+
+See [`examples/`](examples/) for a runner against a local RabbitMQ
+(`docker-compose.yml` included), tool loops, streaming, and agent-to-agent
+delegation.
+
+## Running an agent against RabbitMQ
+
+```python
+from sofias_sdk_lite import AgentRunner, RunnerConfig, RabbitMQConfig, AgentMessage
+
+
+class MyAgentRunner(AgentRunner):
+    settings_class = MySettings
+
+    def build_agent(self, settings, workflow):
+        return (
+            AgentBuilder("my_agent")
+            .with_settings_class(type(settings))
+            .with_response_workflow(workflow)
+            # ... nodes, routing ...
+            .build()
+        )
+
+    def prepare_input(self, task, history, role):
+        return AgentMessage(
+            content=MyInput(message=task.content, role=role),
+            conversation_id=task.conversation_id,
+        )
+
+
+if __name__ == "__main__":
+    MyAgentRunner(
+        RunnerConfig(
+            queue="my-agent-tasks",
+            agent_name="my_agent",
+            rabbitmq=RabbitMQConfig(host="localhost"),
+        )
+    ).run()
+```
+
+## Scope (v1)
+
+Core agent graph, RabbitMQ messaging, and the runner ship today. Memory,
+MCP tool discovery, and LLM adapter implementations are intentionally out
+of scope for v1 — the SDK ships the relevant protocols
+(`MemoryProvider`, `ToolProvider`, `LLMCallable`) so you can plug in your
+own, and these become optional extras in a later release.
+
+## License
+
+Apache-2.0. See [LICENSE](LICENSE).

sofias_sdk_lite-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[project]
+name = "sofias-sdk-lite"
+version = "0.1.0"
+description = "Build agents on the Sofias agent graph and run them over RabbitMQ."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "Apache-2.0"
+dependencies = [
+    "pydantic>=2.0",
+    "aio-pika>=9.0.0",
+    "rstream>=1.0.0",
+    "nh3>=0.3.6",
+]
+
+[project.optional-dependencies]
+docs = [
+    "mkdocs-material>=9.5",
+    "mkdocstrings[python]>=0.25",
+]
+
+[[tool.uv.index]]
+name = "pypi"
+url = "https://pypi.org/simple"
+default = true
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+addopts = "-ra"
+asyncio_mode = "auto"
+markers = ["integration: requires a running RabbitMQ broker"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.pyright]
+include = ["src"]
+typeCheckingMode = "strict"
+
+[build-system]
+requires = ["uv_build>=0.10.0,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23.0",
+    "pytest-cov>=5.0",
+    "ruff>=0.4.0",
+    "pyright>=1.1.408",
+]

sofias_sdk_lite-0.1.0/pyproject.toml.orig

@@ -0,0 +1,51 @@
+[project]
+name = "sofias-sdk-lite"
+version = "0.1.0"
+description = "Build agents on the Sofias agent graph and run them over RabbitMQ."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "Apache-2.0"
+dependencies = [
+    "pydantic>=2.0",
+    "aio-pika>=9.0.0",
+    "rstream>=1.0.0",
+    "nh3>=0.3.6",
+]
+
+[project.optional-dependencies]
+docs = [
+    "mkdocs-material>=9.5",
+    "mkdocstrings[python]>=0.25",
+]
+
+[[tool.uv.index]]
+name = "pypi"
+url = "https://pypi.org/simple"
+default = true
+
+[build-system]
+requires = ["uv_build>=0.10.0,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23.0",
+    "pytest-cov>=5.0",
+    "ruff>=0.4.0",
+    "pyright>=1.1.408",
+]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+addopts = "-ra"
+asyncio_mode = "auto"
+markers = ["integration: requires a running RabbitMQ broker"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.pyright]
+include = ["src"]
+typeCheckingMode = "strict"

sofias_sdk_lite-0.1.0/src/sofias_sdk_lite/__init__.py

@@ -0,0 +1,262 @@
+"""Sofias Agents SDK — build agents on the Sofias agent graph and run them over RabbitMQ.
+
+Quickstart::
+
+    from sofias_sdk_lite import AgentBuilder, InputContract, NodeContract, OutputContract
+
+    class GreetInput(InputContract):
+        name: str
+
+    class GreetOutput(OutputContract):
+        greeting: str
+
+    agent = (
+        AgentBuilder("hello_agent", version="0.1.0")
+        .with_settings_class(MySettings)
+        .with_contract(input_schema=GreetInput, output_schema=GreetOutput)
+        .add_function_node(
+            "greeter",
+            NodeContract(input_schema=GreetInput, output_schema=GreetOutput),
+            process_fn=lambda data, ctx: {"greeting": f"Hello, {data['name']}!"},
+        )
+        .set_entry_node("greeter")
+        .set_terminal("greeter")
+        .build()
+    )
+
+See the docs site for the full guide: agent graph concepts, running an agent
+against RabbitMQ, streaming, delegation, and testing.
+"""
+
+from __future__ import annotations
+
+from sofias_sdk_lite.agent import (
+    Agent,
+    AgentBuildError,
+    AgentBuilder,
+    AgentConfig,
+    AgentLLMConfig,
+    AgentMiddleware,
+    BaseDelegationResponseWorkflow,
+    ExecutionContext,
+    LoggingMiddleware,
+    PublishFn,
+    ResponseWorkflow,
+    StreamingResponseWorkflow,
+    get_execution_context,
+    set_execution_context,
+)
+from sofias_sdk_lite.config import (
+    AgentSettings,
+    BaseAgentSettings,
+    ConfigSource,
+    EnvConfigSource,
+    RuntimeConfigError,
+    SDKConfig,
+    SettingsResolver,
+    StaticConfigSource,
+)
+from sofias_sdk_lite.contracts import (
+    AgentContract,
+    AgentMessage,
+    AgentResponse,
+    DelegationRequest,
+    DelegationResponse,
+    DelegationStatus,
+    InputContract,
+    NodeContract,
+    OutputContract,
+    ResponseStatus,
+    StrictContract,
+)
+from sofias_sdk_lite.errors import (
+    AgentSDKError,
+    CircuitBreakerConfig,
+    ConfigSourceError,
+    ContractValidationError,
+    ErrorHandler,
+    ErrorHandlerConfig,
+    GraphExecutionError,
+    InputValidationError,
+    NodeExecutionError,
+    OutputValidationError,
+    RetryPolicy,
+    RoutingError,
+    ToolExecutionError,
+)
+from sofias_sdk_lite.llm import (
+    LLMCallable,
+    LLMResponse,
+    StreamableLLMCallable,
+    TokenUsage,
+    ToolCall,
+    ToolSpec,
+)
+from sofias_sdk_lite.messaging import (
+    AgentTaskMessage,
+    ApiTaskMessage,
+    ChatRequest,
+    ChatResponse,
+    FileContent,
+    FileMessage,
+    StreamFragment,
+)
+from sofias_sdk_lite.nodes import (
+    AggregatorNode,
+    AggregatorNodeConfig,
+    BaseNode,
+    DelegationNode,
+    DelegationNodeConfig,
+    DelegationTransport,
+    FunctionNode,
+    LLMNode,
+    LLMNodeConfig,
+    NodeType,
+    NullDelegationTransport,
+    PlannerNode,
+)
+from sofias_sdk_lite.rabbitmq import (
+    AckPolicy,
+    RabbitMQClient,
+    RabbitMQConfig,
+    RabbitMQConsumer,
+    RabbitMQDelegationTransport,
+    RabbitMQPublisher,
+    RabbitMQRPCClient,
+)
+from sofias_sdk_lite.routing import (
+    CompositeStrategy,
+    ConditionalStrategy,
+    ConfidenceThresholdStrategy,
+    FanOutStrategy,
+    FieldPresenceStrategy,
+    FieldValueStrategy,
+    Router,
+    RoutingStrategy,
+    StaticRoute,
+)
+from sofias_sdk_lite.runner import AgentRunner, RunnerConfig
+from sofias_sdk_lite.state import (
+    ConversationStateProvider,
+    HistoryProvider,
+    InMemoryHistory,
+    InMemoryStateProvider,
+    MemoryProvider,
+    Message,
+)
+from sofias_sdk_lite.workflows import ChatResponseWorkflow, NullWorkflow
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    # Agent
+    "Agent",
+    "AgentBuilder",
+    "AgentBuildError",
+    "AgentConfig",
+    "AgentLLMConfig",
+    "AgentMiddleware",
+    "LoggingMiddleware",
+    "ExecutionContext",
+    "get_execution_context",
+    "set_execution_context",
+    "ResponseWorkflow",
+    "StreamingResponseWorkflow",
+    "BaseDelegationResponseWorkflow",
+    "PublishFn",
+    # Config
+    "AgentSettings",
+    "BaseAgentSettings",
+    "SDKConfig",
+    "SettingsResolver",
+    "RuntimeConfigError",
+    "ConfigSource",
+    "StaticConfigSource",
+    "EnvConfigSource",
+    # Contracts
+    "StrictContract",
+    "InputContract",
+    "OutputContract",
+    "NodeContract",
+    "AgentContract",
+    "AgentMessage",
+    "AgentResponse",
+    "ResponseStatus",
+    "DelegationRequest",
+    "DelegationResponse",
+    "DelegationStatus",
+    # Errors
+    "AgentSDKError",
+    "ContractValidationError",
+    "InputValidationError",
+    "OutputValidationError",
+    "NodeExecutionError",
+    "RoutingError",
+    "ToolExecutionError",
+    "GraphExecutionError",
+    "ConfigSourceError",
+    "ErrorHandler",
+    "ErrorHandlerConfig",
+    "RetryPolicy",
+    "CircuitBreakerConfig",
+    # LLM protocol
+    "LLMCallable",
+    "StreamableLLMCallable",
+    "LLMResponse",
+    "TokenUsage",
+    "ToolCall",
+    "ToolSpec",
+    # Messaging
+    "AgentTaskMessage",
+    "ApiTaskMessage",
+    "ChatRequest",
+    "ChatResponse",
+    "StreamFragment",
+    "FileMessage",
+    "FileContent",
+    # Nodes
+    "BaseNode",
+    "NodeType",
+    "LLMNode",
+    "LLMNodeConfig",
+    "FunctionNode",
+    "AggregatorNode",
+    "AggregatorNodeConfig",
+    "DelegationNode",
+    "DelegationNodeConfig",
+    "DelegationTransport",
+    "NullDelegationTransport",
+    "PlannerNode",
+    # Routing
+    "Router",
+    "RoutingStrategy",
+    "StaticRoute",
+    "FieldValueStrategy",
+    "FieldPresenceStrategy",
+    "ConditionalStrategy",
+    "ConfidenceThresholdStrategy",
+    "CompositeStrategy",
+    "FanOutStrategy",
+    # RabbitMQ
+    "RabbitMQConfig",
+    "RabbitMQClient",
+    "RabbitMQConsumer",
+    "RabbitMQPublisher",
+    "RabbitMQRPCClient",
+    "RabbitMQDelegationTransport",
+    "AckPolicy",
+    # Runner
+    "AgentRunner",
+    "RunnerConfig",
+    # Workflows
+    "ChatResponseWorkflow",
+    "NullWorkflow",
+    # State
+    "ConversationStateProvider",
+    "InMemoryStateProvider",
+    "MemoryProvider",
+    "HistoryProvider",
+    "InMemoryHistory",
+    "Message",
+]

sofias_sdk_lite-0.1.0/src/sofias_sdk_lite/agent/__init__.py

@@ -0,0 +1,67 @@
+"""Agent module: the Agent executor, builder, and supporting runtime pieces."""
+
+from sofias_sdk_lite.agent.agent import Agent
+from sofias_sdk_lite.agent.agent_builder import AgentBuildError, AgentBuilder
+from sofias_sdk_lite.agent.agent_config import AgentConfig, AgentLLMConfig
+from sofias_sdk_lite.agent.execution_context import (
+    ExecutionContext,
+    TokenAccumulator,
+    get_execution_context,
+    set_execution_context,
+)
+from sofias_sdk_lite.agent.middleware import (
+    AgentMiddleware,
+    LoggingMiddleware,
+    TimingMiddleware,
+)
+from sofias_sdk_lite.agent.response_workflow import (
+    BaseDelegationResponseWorkflow,
+    PublishFn,
+    ResponseWorkflow,
+    StreamingResponseWorkflow,
+)
+from sofias_sdk_lite.agent.streaming import (
+    AgentCompleteEvent,
+    AgentErrorEvent,
+    AggregationResponseEvent,
+    NodeCompleteEvent,
+    NodeStartEvent,
+    StreamEvent,
+    TextChunkEvent,
+    ToolCallResultEvent,
+    ToolCallStartEvent,
+)
+
+__all__ = [
+    # Agent
+    "Agent",
+    "get_execution_context",
+    "set_execution_context",
+    "ExecutionContext",
+    "TokenAccumulator",
+    # Builder
+    "AgentBuilder",
+    "AgentBuildError",
+    # Config
+    "AgentConfig",
+    "AgentLLMConfig",
+    # Middleware
+    "AgentMiddleware",
+    "LoggingMiddleware",
+    "TimingMiddleware",
+    # Response workflow
+    "ResponseWorkflow",
+    "StreamingResponseWorkflow",
+    "BaseDelegationResponseWorkflow",
+    "PublishFn",
+    # Streaming events
+    "StreamEvent",
+    "TextChunkEvent",
+    "ToolCallStartEvent",
+    "ToolCallResultEvent",
+    "NodeStartEvent",
+    "NodeCompleteEvent",
+    "AgentCompleteEvent",
+    "AggregationResponseEvent",
+    "AgentErrorEvent",
+]