agentic-workflow-orchestrator 1.0.0__tar.gz

agentic_workflow_orchestrator-1.0.0/CHANGELOG.md

@@ -0,0 +1,51 @@
+# Changelog
+
+All notable changes to the Orchestrator SDK will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-06-18
+
+### Added
+- Core orchestration engine: DAG scheduler, worker pool, rate limiting
+- Skill and tool registration system
+- LLM integration with Anthropic (Claude) support and MockLLM for testing
+- MCP (Model Context Protocol) support with three levels of abstraction:
+  - Level 1: Direct tool calls (stateless)
+  - Level 2: Pre-wrapped MCP skills (semantic)
+  - Level 3: Managed MCP servers (cached, lifecycle-managed)
+- Workflow templating: `${input.x}`, `${taskId.output}` references
+- Retry policies: exponential backoff, jitter support
+- Per-task and per-provider rate limiting
+- Comprehensive reporting: timing, LLM token usage, critical path, decisions
+- Python SDK with async-ready API
+- Go reference engine (gRPC + stdio transport)
+- Full test suite (unit + integration + end-to-end)
+- Four runnable examples (hello world, parallel pipeline, LLM review, MCP flexible)
+
+### Documentation
+- Design document (DESIGN.md)
+- Quick start guide (QUICKSTART.md)
+- Testing guide (TESTING.md)
+- MCP integration reference (MCP_INTEGRATION.md)
+- Full API reference in docstrings
+
+## Roadmap
+
+### v0.2.0 (planned)
+- [ ] Dynamic fan-out (foreach loops spawning N parallel children)
+- [ ] Sub-workflows (nested workflow execution)
+- [ ] Durable state persistence (Redis/Postgres backend)
+- [ ] Multi-tenant service mode with resumable runs
+- [ ] Human-in-the-loop approval tasks
+- [ ] Automatic reconnect for failed MCP servers
+
+### v1.0.0 (planned)
+- [ ] JavaScript/TypeScript SDK
+- [ ] Java SDK
+- [ ] Native Go client library
+- [ ] Distributed workflow execution across multiple machines
+- [ ] Advanced observability: distributed tracing, metrics export
+- [ ] Workflow visualization dashboard
+- [ ] Policy engine for compliance checks

agentic_workflow_orchestrator-1.0.0/MANIFEST.in

@@ -0,0 +1,11 @@
+include README.md
+include LICENSE
+include CHANGELOG.md
+recursive-include orchestrator py.typed
+
+# Exclude test and example files from distributions
+exclude tests/
+exclude examples/
+recursive-exclude . __pycache__
+recursive-exclude . *.pyc
+recursive-exclude . .pytest_cache

agentic_workflow_orchestrator-1.0.0/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: agentic-workflow-orchestrator
+Version: 1.0.0
+Summary: Orchestrate multi-agent workflows with autonomous reasoning, parallelism, rate limiting, and LLM integration
+Home-page: https://github.com/org/orchestrator
+Author: Manikandan Kasi
+Author-email: Orchestrator Team <info@orchestrator.dev>
+License: Apache License 2.0
+Project-URL: Homepage, https://github.com/org/orchestrator
+Project-URL: Documentation, https://github.com/org/orchestrator/blob/main/QUICKSTART.md
+Project-URL: Repository, https://github.com/org/orchestrator
+Project-URL: Issues, https://github.com/org/orchestrator/issues
+Keywords: orchestration,workflow,multi-agent,agent,concurrency,rate-limiting,llm,mcp,asyncio
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: llm-anthropic
+Requires-Dist: anthropic>=0.7.0; extra == "llm-anthropic"
+Provides-Extra: llm-openai
+Requires-Dist: openai>=1.0.0; extra == "llm-openai"
+Provides-Extra: llm-gemini
+Requires-Dist: google-generativeai>=0.3.0; extra == "llm-gemini"
+Provides-Extra: llm-xai
+Requires-Dist: openai>=1.0.0; extra == "llm-xai"
+Provides-Extra: llm-huggingface
+Requires-Dist: transformers>=4.30.0; extra == "llm-huggingface"
+Requires-Dist: torch>=2.0.0; extra == "llm-huggingface"
+Provides-Extra: llm-azure
+Requires-Dist: openai>=1.0.0; extra == "llm-azure"
+Provides-Extra: llm
+Requires-Dist: anthropic>=0.7.0; extra == "llm"
+Requires-Dist: openai>=1.0.0; extra == "llm"
+Requires-Dist: google-generativeai>=0.3.0; extra == "llm"
+Requires-Dist: transformers>=4.30.0; extra == "llm"
+Requires-Dist: torch>=2.0.0; extra == "llm"
+Provides-Extra: engine
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: black>=23.0; extra == "dev"
+Requires-Dist: isort>=5.12; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Dynamic: author
+Dynamic: home-page
+Dynamic: requires-python
+
+# orchestrator (Python reference SDK)
+
+In-process workflow orchestration engine + authoring API. Zero required dependencies
+(stdlib `asyncio`); `pyyaml` is optional (for `.yaml` specs), `anthropic` optional (for the
+real LLM adapter).
+
+## Concepts
+
+- **Workflow** — a DAG of tasks loaded from a template (`Workflow.from_file/from_dict/from_json`).
+- **Skill** — a registered handler `(ctx, inputs) -> output`, sync or `async`.
+- **Tool** — a registered callable a skill invokes via `ctx.call_tool(...)`.
+- **Orchestrator** — runs a workflow, enforcing concurrency + rate limits, and returns a `Report`.
+
+## Minimal usage
+
+```python
+from orchestrator import Workflow, Orchestrator, Registry, MockLLM
+
+reg = Registry()
+
+@reg.tool("http.get")
+def http_get(url):
+    return {"url": url, "ok": True}
+
+@reg.skill("market.fetch")
+def fetch(ctx, inputs):
+    ctx.call_tool("http.get", url=f"/prices/{inputs['ticker']}")
+    ctx.record_decision("selected primary feed", rationale="lowest latency")
+    return {"ticker": inputs["ticker"], "last": 199.4}
+
+@reg.skill("llm.classify")
+def classify(ctx, inputs):
+    r = ctx.llm(messages=[{"role": "user", "content": inputs["text"]}], model="claude-opus-4-8")
+    return r.text
+
+wf = Workflow.from_file("../spec/examples/market-analysis.json")
+report = Orchestrator(reg, llm=MockLLM()).run_sync(wf, inputs={"ticker": "AAPL"})
+print(report.to_json())
+```
+
+## The `ctx` (SkillContext) API
+
+| Member | Purpose |
+|---|---|
+| `ctx.inputs` | resolved task inputs |
+| `ctx.call_tool(name, **kwargs)` | invoke a registered tool |
+| `ctx.llm(messages, tools=, model=, **opts)` | call the configured LLM provider; usage is recorded |
+| `ctx.record_decision(summary, rationale=, data=)` | append a critical decision to the trace |
+| `ctx.log(msg)`, `ctx.attempt`, `ctx.cancelled` | logging / retry attempt / cooperative cancel flag |
+
+## Report
+
+`report.to_dict()` / `report.to_json()` give: `status`, `duration_ms`, per-task
+`{status, duration_ms, attempts, llm, decisions, error}`, `critical_path` (bottleneck chain),
+`totals` (llm tokens, tool calls, retries), `errors`, and the resolved `output`.
+
+## Run
+
+```bash
+python3 examples/run_market.py
+python3 tests/test_engine.py
+```
+
+## Using a real LLM
+
+```python
+from orchestrator import AnthropicProvider, Orchestrator
+orch = Orchestrator(reg, llm=AnthropicProvider(model="claude-opus-4-8"))  # needs ANTHROPIC_API_KEY + `pip install anthropic`
+```
+Confirm current Claude model IDs/limits from the Claude API reference before pinning them.

agentic_workflow_orchestrator-1.0.0/README.md

@@ -0,0 +1,70 @@
+# orchestrator (Python reference SDK)
+
+In-process workflow orchestration engine + authoring API. Zero required dependencies
+(stdlib `asyncio`); `pyyaml` is optional (for `.yaml` specs), `anthropic` optional (for the
+real LLM adapter).
+
+## Concepts
+
+- **Workflow** — a DAG of tasks loaded from a template (`Workflow.from_file/from_dict/from_json`).
+- **Skill** — a registered handler `(ctx, inputs) -> output`, sync or `async`.
+- **Tool** — a registered callable a skill invokes via `ctx.call_tool(...)`.
+- **Orchestrator** — runs a workflow, enforcing concurrency + rate limits, and returns a `Report`.
+
+## Minimal usage
+
+```python
+from orchestrator import Workflow, Orchestrator, Registry, MockLLM
+
+reg = Registry()
+
+@reg.tool("http.get")
+def http_get(url):
+    return {"url": url, "ok": True}
+
+@reg.skill("market.fetch")
+def fetch(ctx, inputs):
+    ctx.call_tool("http.get", url=f"/prices/{inputs['ticker']}")
+    ctx.record_decision("selected primary feed", rationale="lowest latency")
+    return {"ticker": inputs["ticker"], "last": 199.4}
+
+@reg.skill("llm.classify")
+def classify(ctx, inputs):
+    r = ctx.llm(messages=[{"role": "user", "content": inputs["text"]}], model="claude-opus-4-8")
+    return r.text
+
+wf = Workflow.from_file("../spec/examples/market-analysis.json")
+report = Orchestrator(reg, llm=MockLLM()).run_sync(wf, inputs={"ticker": "AAPL"})
+print(report.to_json())
+```
+
+## The `ctx` (SkillContext) API
+
+| Member | Purpose |
+|---|---|
+| `ctx.inputs` | resolved task inputs |
+| `ctx.call_tool(name, **kwargs)` | invoke a registered tool |
+| `ctx.llm(messages, tools=, model=, **opts)` | call the configured LLM provider; usage is recorded |
+| `ctx.record_decision(summary, rationale=, data=)` | append a critical decision to the trace |
+| `ctx.log(msg)`, `ctx.attempt`, `ctx.cancelled` | logging / retry attempt / cooperative cancel flag |
+
+## Report
+
+`report.to_dict()` / `report.to_json()` give: `status`, `duration_ms`, per-task
+`{status, duration_ms, attempts, llm, decisions, error}`, `critical_path` (bottleneck chain),
+`totals` (llm tokens, tool calls, retries), `errors`, and the resolved `output`.
+
+## Run
+
+```bash
+python3 examples/run_market.py
+python3 tests/test_engine.py
+```
+
+## Using a real LLM
+
+```python
+from orchestrator import AnthropicProvider, Orchestrator
+orch = Orchestrator(reg, llm=AnthropicProvider(model="claude-opus-4-8"))  # needs ANTHROPIC_API_KEY + `pip install anthropic`
+```
+Confirm current Claude model IDs/limits from the Claude API reference before pinning them.

agentic_workflow_orchestrator-1.0.0/agentic_workflow_orchestrator.egg-info/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: agentic-workflow-orchestrator
+Version: 1.0.0
+Summary: Orchestrate multi-agent workflows with autonomous reasoning, parallelism, rate limiting, and LLM integration
+Home-page: https://github.com/org/orchestrator
+Author: Manikandan Kasi
+Author-email: Orchestrator Team <info@orchestrator.dev>
+License: Apache License 2.0
+Project-URL: Homepage, https://github.com/org/orchestrator
+Project-URL: Documentation, https://github.com/org/orchestrator/blob/main/QUICKSTART.md
+Project-URL: Repository, https://github.com/org/orchestrator
+Project-URL: Issues, https://github.com/org/orchestrator/issues
+Keywords: orchestration,workflow,multi-agent,agent,concurrency,rate-limiting,llm,mcp,asyncio
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: llm-anthropic
+Requires-Dist: anthropic>=0.7.0; extra == "llm-anthropic"
+Provides-Extra: llm-openai
+Requires-Dist: openai>=1.0.0; extra == "llm-openai"
+Provides-Extra: llm-gemini
+Requires-Dist: google-generativeai>=0.3.0; extra == "llm-gemini"
+Provides-Extra: llm-xai
+Requires-Dist: openai>=1.0.0; extra == "llm-xai"
+Provides-Extra: llm-huggingface
+Requires-Dist: transformers>=4.30.0; extra == "llm-huggingface"
+Requires-Dist: torch>=2.0.0; extra == "llm-huggingface"
+Provides-Extra: llm-azure
+Requires-Dist: openai>=1.0.0; extra == "llm-azure"
+Provides-Extra: llm
+Requires-Dist: anthropic>=0.7.0; extra == "llm"
+Requires-Dist: openai>=1.0.0; extra == "llm"
+Requires-Dist: google-generativeai>=0.3.0; extra == "llm"
+Requires-Dist: transformers>=4.30.0; extra == "llm"
+Requires-Dist: torch>=2.0.0; extra == "llm"
+Provides-Extra: engine
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: black>=23.0; extra == "dev"
+Requires-Dist: isort>=5.12; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Dynamic: author
+Dynamic: home-page
+Dynamic: requires-python
+
+# orchestrator (Python reference SDK)
+
+In-process workflow orchestration engine + authoring API. Zero required dependencies
+(stdlib `asyncio`); `pyyaml` is optional (for `.yaml` specs), `anthropic` optional (for the
+real LLM adapter).
+
+## Concepts
+
+- **Workflow** — a DAG of tasks loaded from a template (`Workflow.from_file/from_dict/from_json`).
+- **Skill** — a registered handler `(ctx, inputs) -> output`, sync or `async`.
+- **Tool** — a registered callable a skill invokes via `ctx.call_tool(...)`.
+- **Orchestrator** — runs a workflow, enforcing concurrency + rate limits, and returns a `Report`.
+
+## Minimal usage
+
+```python
+from orchestrator import Workflow, Orchestrator, Registry, MockLLM
+
+reg = Registry()
+
+@reg.tool("http.get")
+def http_get(url):
+    return {"url": url, "ok": True}
+
+@reg.skill("market.fetch")
+def fetch(ctx, inputs):
+    ctx.call_tool("http.get", url=f"/prices/{inputs['ticker']}")
+    ctx.record_decision("selected primary feed", rationale="lowest latency")
+    return {"ticker": inputs["ticker"], "last": 199.4}
+
+@reg.skill("llm.classify")
+def classify(ctx, inputs):
+    r = ctx.llm(messages=[{"role": "user", "content": inputs["text"]}], model="claude-opus-4-8")
+    return r.text
+
+wf = Workflow.from_file("../spec/examples/market-analysis.json")
+report = Orchestrator(reg, llm=MockLLM()).run_sync(wf, inputs={"ticker": "AAPL"})
+print(report.to_json())
+```
+
+## The `ctx` (SkillContext) API
+
+| Member | Purpose |
+|---|---|
+| `ctx.inputs` | resolved task inputs |
+| `ctx.call_tool(name, **kwargs)` | invoke a registered tool |
+| `ctx.llm(messages, tools=, model=, **opts)` | call the configured LLM provider; usage is recorded |
+| `ctx.record_decision(summary, rationale=, data=)` | append a critical decision to the trace |
+| `ctx.log(msg)`, `ctx.attempt`, `ctx.cancelled` | logging / retry attempt / cooperative cancel flag |
+
+## Report
+
+`report.to_dict()` / `report.to_json()` give: `status`, `duration_ms`, per-task
+`{status, duration_ms, attempts, llm, decisions, error}`, `critical_path` (bottleneck chain),
+`totals` (llm tokens, tool calls, retries), `errors`, and the resolved `output`.
+
+## Run
+
+```bash
+python3 examples/run_market.py
+python3 tests/test_engine.py
+```
+
+## Using a real LLM
+
+```python
+from orchestrator import AnthropicProvider, Orchestrator
+orch = Orchestrator(reg, llm=AnthropicProvider(model="claude-opus-4-8"))  # needs ANTHROPIC_API_KEY + `pip install anthropic`
+```
+Confirm current Claude model IDs/limits from the Claude API reference before pinning them.

agentic_workflow_orchestrator-1.0.0/agentic_workflow_orchestrator.egg-info/SOURCES.txt

@@ -0,0 +1,31 @@
+CHANGELOG.md
+MANIFEST.in
+README.md
+pyproject.toml
+setup.py
+./orchestrator/__init__.py
+./orchestrator/engine.py
+./orchestrator/llm.py
+./orchestrator/mcp_integration.py
+./orchestrator/py.typed
+./orchestrator/ratelimit.py
+./orchestrator/registry.py
+./orchestrator/report.py
+./orchestrator/spec.py
+agentic_workflow_orchestrator.egg-info/PKG-INFO
+agentic_workflow_orchestrator.egg-info/SOURCES.txt
+agentic_workflow_orchestrator.egg-info/dependency_links.txt
+agentic_workflow_orchestrator.egg-info/requires.txt
+agentic_workflow_orchestrator.egg-info/top_level.txt
+orchestrator/__init__.py
+orchestrator/engine.py
+orchestrator/llm.py
+orchestrator/mcp_integration.py
+orchestrator/py.typed
+orchestrator/ratelimit.py
+orchestrator/registry.py
+orchestrator/report.py
+orchestrator/spec.py
+tests/test_engine.py
+tests/test_go_engine.py
+tests/test_mcp_integration.py

agentic_workflow_orchestrator-1.0.0/agentic_workflow_orchestrator.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

agentic_workflow_orchestrator-1.0.0/agentic_workflow_orchestrator.egg-info/requires.txt

@@ -0,0 +1,35 @@
+
+[dev]
+pytest>=7.0
+pytest-cov>=4.0
+black>=23.0
+isort>=5.12
+mypy>=1.0
+
+[engine]
+
+[llm]
+anthropic>=0.7.0
+openai>=1.0.0
+google-generativeai>=0.3.0
+transformers>=4.30.0
+torch>=2.0.0
+
+[llm-anthropic]
+anthropic>=0.7.0
+
+[llm-azure]
+openai>=1.0.0
+
+[llm-gemini]
+google-generativeai>=0.3.0
+
+[llm-huggingface]
+transformers>=4.30.0
+torch>=2.0.0
+
+[llm-openai]
+openai>=1.0.0
+
+[llm-xai]
+openai>=1.0.0

agentic_workflow_orchestrator-1.0.0/agentic_workflow_orchestrator.egg-info/top_level.txt

@@ -0,0 +1 @@
+orchestrator

agentic_workflow_orchestrator-1.0.0/orchestrator/__init__.py

@@ -0,0 +1,63 @@
+"""Multi-agent workflow orchestration SDK — Python reference implementation.
+
+Quick start:
+
+    from orchestrator import Workflow, Orchestrator, Registry, MockLLM
+
+    reg = Registry()
+
+    @reg.skill("market.fetch")
+    def fetch(ctx, inputs):
+        ctx.record_decision("selected primary feed", rationale="lowest latency")
+        return {"ticker": inputs["ticker"], "last": 199.4}
+
+    wf = Workflow.from_file("spec/examples/market-analysis.json")
+    report = Orchestrator(reg, llm=MockLLM()).run_sync(wf, {"ticker": "AAPL"})
+    print(report.to_json())
+"""
+from .engine import Orchestrator, TaskFailed
+from .llm import (
+    AnthropicProvider,
+    AzureOpenAIProvider,
+    GeminiProvider,
+    HuggingFaceProvider,
+    LlmProvider,
+    LlmResult,
+    MockLLM,
+    OpenAIProvider,
+    XAIProvider,
+)
+from .ratelimit import TokenBucket
+from .registry import Registry, SkillContext
+from .report import Decision, LlmUsage, Report, TaskSpan, Totals
+from .spec import RateLimit, Retry, SpecError, Task, Workflow, resolve_template
+
+__all__ = [
+    "Orchestrator",
+    "TaskFailed",
+    "Registry",
+    "SkillContext",
+    "Workflow",
+    "Task",
+    "RateLimit",
+    "Retry",
+    "SpecError",
+    "resolve_template",
+    "Report",
+    "TaskSpan",
+    "Decision",
+    "LlmUsage",
+    "Totals",
+    "LlmProvider",
+    "LlmResult",
+    "MockLLM",
+    "AnthropicProvider",
+    "OpenAIProvider",
+    "GeminiProvider",
+    "XAIProvider",
+    "HuggingFaceProvider",
+    "AzureOpenAIProvider",
+    "TokenBucket",
+]
+
+__version__ = "0.1.0"