choreo-mini 0.1.0__tar.gz

choreo_mini-0.1.0/LICENSE

@@ -0,0 +1,148 @@
+Choreo-Mini Source License
+Version 1.2 (March 2026)
+
+Copyright (c) 2026 Sivasathivel Kandasamy
+https://www.linkedin.com/in/sivasathivelkandasamy/
+
+This license allows broad use of Choreo-Mini, including commercial use as a
+library or dependency, while restricting third-party productization of
+Choreo-Mini itself.
+
+1. Definitions
+
+"Software" means this project, including its source code, build artifacts,
+and documentation released under this license.
+
+"Derivative Work" means any modification of the Software, or any work based
+on the Software, where Software code is changed, extended, or incorporated in
+a way that creates a derived codebase.
+
+For clarity, merely importing, linking, calling public APIs, or configuring
+the Software without modifying its code does not by itself create a
+Derivative Work.
+
+"Larger Work" means software that uses, links to, or depends on the Software,
+but is otherwise independently developed and not itself a Derivative Work.
+
+"Productize" means, for third parties, to do any of the following with the
+Software or a Derivative Work:
+(a) sell, license, or sublicense it as a product, plugin, extension, toolkit,
+    model service, or API offering;
+(b) offer it as a hosted or managed service (including SaaS) where users
+    access its functionality over a network;
+(c) provide paid access to the Software or a Derivative Work, including when
+    bundled with other services.
+
+"Internal Use" means use within your own legal entity and its controlled
+entities, where no external party receives direct access to the Software or a
+Derivative Work as a standalone offering.
+
+2. License Grant
+
+Subject to compliance with this license, you are granted a non-exclusive,
+worldwide, royalty-free right to:
+(a) use, run, and reproduce the Software for any purpose, including commercial
+    Internal Use;
+(b) modify the Software and create Derivative Works;
+(c) use the Software inside Larger Works, including proprietary applications;
+(d) distribute unmodified copies of the Software, provided this license and
+    attribution notices are included.
+
+3. Productization Restriction
+
+Except for the original author (Sivasathivel Kandasamy), no person or entity
+may Productize the Software or any Derivative Work under this license.
+
+This license does not provide a case-by-case approval or exception process for
+third-party Productization.
+
+Clarification: using the Software as an internal dependency, build tool, or
+embedded library inside a Larger Work does not by itself constitute
+Productization, so long as the Software is not offered to third parties as a
+standalone product, API, plugin, extension, or hosted platform.
+
+Safe-harbor examples (permitted under this license):
+(a) using the Software in internal enterprise workflows, including commercial
+    business operations;
+(b) shipping a proprietary Larger Work that depends on the unmodified
+    Software, with required license notice retained;
+(c) using the Software in private build, testing, or deployment tooling.
+
+Examples of prohibited third-party Productization:
+(a) selling a modified fork, plugin, or extension based on the Software;
+(b) offering a paid hosted API or SaaS where users access Software or
+    Derivative Work functionality over a network;
+(c) charging for direct access to Software or Derivative Work capabilities,
+    even when bundled with other paid services.
+
+4. Copyleft for Distributed or Hosted Derivatives
+
+If you distribute a Derivative Work to third parties, or make a Derivative
+Work available to third parties over a network (for example as a hosted API or
+service), you must:
+(a) provide the complete corresponding source code of that Derivative Work;
+(b) license that Derivative Work under this same license;
+(c) include this license text and preserve copyright notices;
+(d) clearly mark modified files.
+
+Scope limitation: this clause applies to the Software and Derivative Work
+portions only. It does not require disclosure of independent source code in a
+Larger Work that is not derived from the Software.
+
+5. Citation and Attribution
+
+Any public materials or user-facing interface that references, demonstrates,
+or provides access to software using the Software or a Derivative Work must
+include visible attribution containing at least:
+- Project: Choreo-Mini
+- Author: Sivasathivel Kandasamy
+- Source: https://github.com/Sivasathivel/Choreo-mini
+
+Examples include public repositories, documentation sites, demo pages,
+benchmark publications, product websites, and service UI pages. Backend-only
+private deployments with no public-facing materials are not required to
+display attribution.
+
+6. Contributions and Relicensing Rights
+
+By submitting any contribution for inclusion in this project (including pull
+requests, patches, or code changes), you agree that:
+(a) your contribution may be distributed under this license; and
+(b) you grant the author a perpetual, worldwide, irrevocable, royalty-free
+    right to use, modify, sublicense, and relicense your contribution,
+    including in future dual-licensed, commercial, or enterprise editions.
+
+You represent that you have the legal right to submit the contribution under
+these terms.
+
+7. Patent and Trademark
+
+Each contributor grants a non-exclusive, royalty-free patent license for patent
+claims necessarily infringed by their contribution as included in the Software.
+No trademark rights are granted by this license.
+
+8. Reserved Author Rights and Future Licensing
+
+The author reserves the exclusive right to:
+(a) publish enterprise, dual-licensed, or otherwise differently licensed
+    future versions; and
+(b) modify license terms for future releases.
+
+Rights granted for previously released versions are not retroactively revoked
+for recipients who remain in compliance with the license applicable to those
+versions.
+
+9. Disclaimer of Warranty and Limitation of Liability
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHOR OR
+CONTRIBUTORS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN
+AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+10. Termination
+
+Any material breach of this license automatically terminates rights granted
+under it. Rights may be reinstated only by explicit written notice from the
+author.

choreo_mini-0.1.0/PKG-INFO

@@ -0,0 +1,232 @@
+Metadata-Version: 2.4
+Name: choreo-mini
+Version: 0.1.0
+Summary: A lightweight Python meta-framework for building, experimenting with, and orchestrating LLM-based agents across multiple runtimes.
+Author: Sivasathivel Kandasamy
+License: Choreo-Mini Source License 1.2
+Project-URL: Homepage, https://github.com/Sivasathivel/Choreo-mini
+Project-URL: Source, https://github.com/Sivasathivel/Choreo-mini
+Project-URL: Author LinkedIn, https://www.linkedin.com/in/sivasathivelkandasamy/
+Keywords: llm,agents,orchestration,langgraph,crewai,autogen,ai,workflow,agentic
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: Other/Proprietary 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: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: jinja2>=3.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: langgraph; extra == "dev"
+Dynamic: license-file
+
+# Choreo-Mini
+
+**A lightweight Python meta-framework for building, experimenting with, and orchestrating LLM-based agents.**
+
+Modern agent frameworks — LangGraph, CrewAI, AutoGen — each solve similar orchestration problems but introduce fragmented abstractions and steep learning curves. Choreo-Mini provides a Python-native developer experience that allows engineers to prototype agent workflows quickly while retaining the flexibility to run them on different orchestration runtimes.
+
+Instead of forcing developers to commit to a single framework, Choreo-Mini acts as an orchestration meta-layer: you express your workflow once in plain Python, and it compiles it to your target runtime.
+
+---
+
+## How it works
+
+```
+Your Python Workflow
+        │
+        ▼
+    AST Parser  ── extracts agents, services, control flow, state mutations
+        │
+        ▼
+  Intermediate Representation
+        │
+        ▼
+  Jinja2 Template Compiler
+        │
+    ┌───┴────────────────┐
+    ▼         ▼          ▼
+LangGraph  CrewAI    AutoGen
+```
+
+---
+
+## Status
+
+Choreo-Mini is an actively developed prototype. The **LangGraph** backend is the most mature path, supporting branch-aware conditional routing, loop budgets, and service node dispatch. **CrewAI** and **AutoGen** backends produce structurally correct scaffolding and are being extended for deeper runtime fidelity.
+
+---
+
+## Installation
+
+```bash
+pip install choreo-mini
+```
+
+---
+
+## Quick Start
+
+**Define your workflow once in plain Python:**
+
+```python
+# examples/my_workflow.py
+from choreo_mini.core.workflow import Workflow
+from choreo_mini.core.nodes import AgentNode, ServiceNode
+
+wf = Workflow("support", enable_profiling=True)
+
+# agents auto-register with the workflow on creation
+classifier = AgentNode(wf, "Classifier", role="ticket triage")
+specialist  = AgentNode(wf, "Specialist",  role="issue resolver")
+
+
+def main():
+    while True:
+        ticket = input("Ticket> ")
+        if not ticket.strip():
+            break
+        category = wf.send("Classifier", ticket)
+        response = wf.send("Specialist", f"{category.content}: {ticket}")
+        print(response.content)
+```
+
+**Compile to any supported runtime:**
+
+```bash
+# to LangGraph
+choreo_mini -f examples/my_workflow.py -b langgraph -o output/langgraph_output.py
+
+# to CrewAI
+choreo_mini -f examples/my_workflow.py -b crewai  -o output/crewai_output.py
+
+# to AutoGen
+choreo_mini -f examples/my_workflow.py -b autogen -o output/autogen_output.py
+```
+
+**Run the generated LangGraph app directly:**
+
+```python
+from output.langgraph_output import app
+from choreo_mini import Workflow, AgentNode
+from choreo_mini.core.llm import LLM
+
+wf = Workflow("support", enable_profiling=True)
+AgentNode(wf, "Classifier", role="triage", llm=LLM.create("openai", api_key="..."))
+AgentNode(wf, "Specialist",  role="resolver", llm=LLM.create("openai", api_key="..."))
+
+result = app.invoke({"wf": wf, "input": "login broken", "messages": [], "loop_budget": 1})
+print(result["last_response"])
+```
+
+---
+
+## Python API
+
+```python
+from choreo_mini import Workflow, AgentNode, ServiceNode, LLM, CustomLLM
+
+# create a workflow — enable_profiling tracks latency and memory per agent
+wf = Workflow("myflow", enable_profiling=True)
+
+# attach agents with a real or custom LLM
+A1 = AgentNode(wf, "Greeter",   role="greeter",   llm=LLM.create("openai",    api_key="..."))
+A2 = AgentNode(wf, "Responder", role="responder", llm=LLM.create("anthropic", api_key="..."))
+
+# CustomLLM wraps any callable — great for local models or mocks
+A3 = AgentNode(wf, "Fallback", role="fallback",
+               llm=CustomLLM(lambda prompt, **kw: f"Fallback: {prompt}"))
+
+# service nodes wrap arbitrary data functions
+loader = ServiceNode(wf, "Loader", service_fn=lambda wf, path: open(path).read())
+
+# send a message to an agent — history and profiling handled automatically
+response = wf.send("Greeter", "Hello")
+print(response.content)
+
+# inspect profiling
+print(wf.get_profile("Greeter"))  # {"calls": 1, "total_latency": ..., "total_memory": ...}
+```
+
+---
+
+## Observability
+
+When `enable_profiling=True`, Choreo-Mini instruments every agent call automatically:
+
+| Metric | Description |
+|--------|-------------|
+| `call_count` | Number of times the agent was invoked |
+| `total_latency` | Cumulative wall-clock inference time (seconds) |
+| `total_memory` | Cumulative memory delta across calls (bytes) |
+| `history` | Full conversation history per agent |
+
+This makes it straightforward to compare runtimes or detect bottlenecks before committing to a specific framework.
+
+---
+
+## Supported LLM Providers
+
+| Provider | Class | Notes |
+|----------|-------|-------|
+| OpenAI | `LLM.create("openai", api_key=...)` | Stub — wire real `openai` client in `generate()` |
+| Anthropic | `LLM.create("anthropic", api_key=...)` | Stub — wire real `anthropic` client |
+| Gemini | `LLM.create("gemini", api_key=...)` | Stub — wire real Google client |
+| Custom | `CustomLLM(fn)` | Wraps any `(prompt, **kw) -> str` callable |
+
+The provider stubs make scaffolding easy; replace `generate()` with the real SDK call for production.
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/Sivasathivel/Choreo-mini
+cd choreo-mini
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest tests/
+```
+
+CI runs the full regression suite against Python 3.10, 3.11, and 3.12 on every push.
+
+---
+
+## Author
+
+**Sivasathivel Kandasamy** — [LinkedIn](https://www.linkedin.com/in/sivasathivelkandasamy/)
+
+---
+
+## License
+
+This project is released under the [Choreo-Mini Source License](LICENSE).
+
+**What is allowed:**
+- Use choreo-mini as a library or dependency inside any project, including
+    commercial applications and internal enterprise deployments — no restriction.
+- Modify the source and contribute back.
+- Keep your larger application closed source when it only depends on
+    choreo-mini and is not itself a derivative of choreo-mini.
+- Ship a proprietary larger product that uses unmodified choreo-mini as a
+    component, with license notices preserved.
+
+**What is not allowed:**
+- Building and selling a product, plugin, extension, or SaaS where
+    choreo-mini is the core value being offered by a third party.
+- Distributing or hosting a modified derivative of choreo-mini without
+    releasing the derivative source under the same license.
+- Selling paid access to choreo-mini or a derivative API/service, even when
+    bundled with other paid features.
+
+**Other terms:** citation is required in public materials and user-facing
+interfaces (for example docs, demos, public repos, benchmark reports, websites,
+or service UI); contributors grant the author relicensing rights; the author
+reserves the right to publish enterprise/commercial editions. See
+[CONTRIBUTING.md](CONTRIBUTING.md) for contribution terms.

choreo_mini-0.1.0/README.md

@@ -0,0 +1,204 @@
+# Choreo-Mini
+
+**A lightweight Python meta-framework for building, experimenting with, and orchestrating LLM-based agents.**
+
+Modern agent frameworks — LangGraph, CrewAI, AutoGen — each solve similar orchestration problems but introduce fragmented abstractions and steep learning curves. Choreo-Mini provides a Python-native developer experience that allows engineers to prototype agent workflows quickly while retaining the flexibility to run them on different orchestration runtimes.
+
+Instead of forcing developers to commit to a single framework, Choreo-Mini acts as an orchestration meta-layer: you express your workflow once in plain Python, and it compiles it to your target runtime.
+
+---
+
+## How it works
+
+```
+Your Python Workflow
+        │
+        ▼
+    AST Parser  ── extracts agents, services, control flow, state mutations
+        │
+        ▼
+  Intermediate Representation
+        │
+        ▼
+  Jinja2 Template Compiler
+        │
+    ┌───┴────────────────┐
+    ▼         ▼          ▼
+LangGraph  CrewAI    AutoGen
+```
+
+---
+
+## Status
+
+Choreo-Mini is an actively developed prototype. The **LangGraph** backend is the most mature path, supporting branch-aware conditional routing, loop budgets, and service node dispatch. **CrewAI** and **AutoGen** backends produce structurally correct scaffolding and are being extended for deeper runtime fidelity.
+
+---
+
+## Installation
+
+```bash
+pip install choreo-mini
+```
+
+---
+
+## Quick Start
+
+**Define your workflow once in plain Python:**
+
+```python
+# examples/my_workflow.py
+from choreo_mini.core.workflow import Workflow
+from choreo_mini.core.nodes import AgentNode, ServiceNode
+
+wf = Workflow("support", enable_profiling=True)
+
+# agents auto-register with the workflow on creation
+classifier = AgentNode(wf, "Classifier", role="ticket triage")
+specialist  = AgentNode(wf, "Specialist",  role="issue resolver")
+
+
+def main():
+    while True:
+        ticket = input("Ticket> ")
+        if not ticket.strip():
+            break
+        category = wf.send("Classifier", ticket)
+        response = wf.send("Specialist", f"{category.content}: {ticket}")
+        print(response.content)
+```
+
+**Compile to any supported runtime:**
+
+```bash
+# to LangGraph
+choreo_mini -f examples/my_workflow.py -b langgraph -o output/langgraph_output.py
+
+# to CrewAI
+choreo_mini -f examples/my_workflow.py -b crewai  -o output/crewai_output.py
+
+# to AutoGen
+choreo_mini -f examples/my_workflow.py -b autogen -o output/autogen_output.py
+```
+
+**Run the generated LangGraph app directly:**
+
+```python
+from output.langgraph_output import app
+from choreo_mini import Workflow, AgentNode
+from choreo_mini.core.llm import LLM
+
+wf = Workflow("support", enable_profiling=True)
+AgentNode(wf, "Classifier", role="triage", llm=LLM.create("openai", api_key="..."))
+AgentNode(wf, "Specialist",  role="resolver", llm=LLM.create("openai", api_key="..."))
+
+result = app.invoke({"wf": wf, "input": "login broken", "messages": [], "loop_budget": 1})
+print(result["last_response"])
+```
+
+---
+
+## Python API
+
+```python
+from choreo_mini import Workflow, AgentNode, ServiceNode, LLM, CustomLLM
+
+# create a workflow — enable_profiling tracks latency and memory per agent
+wf = Workflow("myflow", enable_profiling=True)
+
+# attach agents with a real or custom LLM
+A1 = AgentNode(wf, "Greeter",   role="greeter",   llm=LLM.create("openai",    api_key="..."))
+A2 = AgentNode(wf, "Responder", role="responder", llm=LLM.create("anthropic", api_key="..."))
+
+# CustomLLM wraps any callable — great for local models or mocks
+A3 = AgentNode(wf, "Fallback", role="fallback",
+               llm=CustomLLM(lambda prompt, **kw: f"Fallback: {prompt}"))
+
+# service nodes wrap arbitrary data functions
+loader = ServiceNode(wf, "Loader", service_fn=lambda wf, path: open(path).read())
+
+# send a message to an agent — history and profiling handled automatically
+response = wf.send("Greeter", "Hello")
+print(response.content)
+
+# inspect profiling
+print(wf.get_profile("Greeter"))  # {"calls": 1, "total_latency": ..., "total_memory": ...}
+```
+
+---
+
+## Observability
+
+When `enable_profiling=True`, Choreo-Mini instruments every agent call automatically:
+
+| Metric | Description |
+|--------|-------------|
+| `call_count` | Number of times the agent was invoked |
+| `total_latency` | Cumulative wall-clock inference time (seconds) |
+| `total_memory` | Cumulative memory delta across calls (bytes) |
+| `history` | Full conversation history per agent |
+
+This makes it straightforward to compare runtimes or detect bottlenecks before committing to a specific framework.
+
+---
+
+## Supported LLM Providers
+
+| Provider | Class | Notes |
+|----------|-------|-------|
+| OpenAI | `LLM.create("openai", api_key=...)` | Stub — wire real `openai` client in `generate()` |
+| Anthropic | `LLM.create("anthropic", api_key=...)` | Stub — wire real `anthropic` client |
+| Gemini | `LLM.create("gemini", api_key=...)` | Stub — wire real Google client |
+| Custom | `CustomLLM(fn)` | Wraps any `(prompt, **kw) -> str` callable |
+
+The provider stubs make scaffolding easy; replace `generate()` with the real SDK call for production.
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/Sivasathivel/Choreo-mini
+cd choreo-mini
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest tests/
+```
+
+CI runs the full regression suite against Python 3.10, 3.11, and 3.12 on every push.
+
+---
+
+## Author
+
+**Sivasathivel Kandasamy** — [LinkedIn](https://www.linkedin.com/in/sivasathivelkandasamy/)
+
+---
+
+## License
+
+This project is released under the [Choreo-Mini Source License](LICENSE).
+
+**What is allowed:**
+- Use choreo-mini as a library or dependency inside any project, including
+    commercial applications and internal enterprise deployments — no restriction.
+- Modify the source and contribute back.
+- Keep your larger application closed source when it only depends on
+    choreo-mini and is not itself a derivative of choreo-mini.
+- Ship a proprietary larger product that uses unmodified choreo-mini as a
+    component, with license notices preserved.
+
+**What is not allowed:**
+- Building and selling a product, plugin, extension, or SaaS where
+    choreo-mini is the core value being offered by a third party.
+- Distributing or hosting a modified derivative of choreo-mini without
+    releasing the derivative source under the same license.
+- Selling paid access to choreo-mini or a derivative API/service, even when
+    bundled with other paid features.
+
+**Other terms:** citation is required in public materials and user-facing
+interfaces (for example docs, demos, public repos, benchmark reports, websites,
+or service UI); contributors grant the author relicensing rights; the author
+reserves the right to publish enterprise/commercial editions. See
+[CONTRIBUTING.md](CONTRIBUTING.md) for contribution terms.

choreo_mini-0.1.0/choreo_mini/__init__.py

@@ -0,0 +1,18 @@
+"""Choreo-Mini — Python-native LLM agent workflow orchestration."""
+
+from choreo_mini.core.workflow import Workflow, AgentState
+from choreo_mini.core.nodes import AgentNode, ServiceNode
+from choreo_mini.core.llm import LLM, CustomLLM, Message
+
+__version__ = "0.1.0"
+__author__ = "Sivasathivel Kandasamy"
+
+__all__ = [
+    "Workflow",
+    "AgentState",
+    "AgentNode",
+    "ServiceNode",
+    "LLM",
+    "CustomLLM",
+    "Message",
+]