Metadata-Version: 2.4
Name: mitosys
Version: 0.3.0
Summary: Controlled mitosis for AI agents — dynamic, effort-scored, recursive task decomposition with regulated division.
Author: Swapnil Bhattacharya
License: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT 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 :: Application Frameworks
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: rich>=13.0.0
Requires-Dist: typer>=0.12.0
Provides-Extra: all
Requires-Dist: autogen-agentchat>=0.4; extra == 'all'
Requires-Dist: crewai>=0.55; extra == 'all'
Requires-Dist: langgraph>=0.2; extra == 'all'
Provides-Extra: autogen
Requires-Dist: autogen-agentchat>=0.4; extra == 'autogen'
Provides-Extra: crewai
Requires-Dist: crewai>=0.55; extra == 'crewai'
Provides-Extra: langgraph
Requires-Dist: langgraph>=0.2; extra == 'langgraph'
Description-Content-Type: text/markdown

# 🧬 Mitosys

> Controlled mitosis for AI agents — dynamic, effort-scored, recursive task decomposition with regulated division.

**Mitosys** is a Python SDK and CLI that routes complex tasks through the [Mitosys backend](https://github.com/NorthCommits/mitosys-backend): an LLM-powered multi-agent system that breaks tasks into parallel sub-tasks, runs them concurrently, and synthesizes a final answer.

_Uncontrolled division is cancer. Mitosys is controlled mitosis._

```bash
pip install mitosys
```

![demo](docs/demo.gif)

---

## Quick Start

```python
import mitosys

# Sync — great for scripts and notebooks
result = mitosys.run("Analyze Q3 sales data across all regions")
print(result.final_answer)
print(f"Used {result.total_agents} agents across {result.max_depth} levels")
```

```python
# Async
import mitosys

result = await mitosys.arun("Analyze Q3 sales data")
print(result.final_answer)
```

```python
# Streaming — get live events as the lifecycle progresses
import mitosys

async for event in mitosys.astream("Write a comprehensive market report"):
    if event.type == "effort":
        print(f"Effort: {event.score}/10  →  {event.recommended_agents} agents")
    elif event.type == "spawn":
        print(f"Born: {event.agent}")
    elif event.type == "final":
        print(event.final_answer)
```

---

## Configuration

| Method | Example |
|--------|---------|
| Default | `https://lumidoc-mitosys-backend.hf.space` |
| Environment variable | `export MITOSYS_URL=http://localhost:8000` |
| Explicit argument | `MitosysClient(url="http://localhost:8000")` |

```python
from mitosys import MitosysClient

client = MitosysClient(
    url="https://my-self-hosted-mitosys.example.com",
    timeout=180,
)
result = await client.arun("Analyze our Q3 sales data")
```

Resolution order: explicit `url=` → `$MITOSYS_URL` → built-in default.

---

## Typed Result Objects

```python
result = mitosys.run("...")

result.task             # str — the original task
result.final_answer     # str — the synthesized answer
result.sub_tasks        # list[SubTask]  — each has .subtask and .effort_hint
result.sub_results      # list[SubResult] — each has .agent, .subtask, .result
result.tree             # AgentTree — walk() yields every node depth-first
result.effort           # EffortScore — .score, .breadth, .depth, .recommended_agents
result.total_agents     # int — how many agents ran in total
result.max_depth        # int — deepest recursion level reached
result.elapsed_seconds  # float
result.raw              # dict — the original backend payload (for power users)
```

---

## Framework Integration

### AutoGen

```python
from mitosys.adapters.autogen import MitosysTool
from autogen_agentchat.agents import AssistantAgent

mitosys_tool = MitosysTool()
agent = AssistantAgent(
    name="researcher",
    model_client=...,
    tools=[mitosys_tool.as_function_tool()],
)
# When the agent decides a task is too complex, it delegates to Mitosys.
```

```bash
pip install mitosys[autogen]
```

### LangGraph

```python
from mitosys.adapters.langgraph import mitosys_node
from langgraph.graph import StateGraph

graph = StateGraph(dict)
graph.add_node("delegate_complex", mitosys_node())
# State must contain "task"; result is written to "mitosys_result".
```

```bash
pip install mitosys[langgraph]
```

### CrewAI

```python
from mitosys.adapters.crewai import MitosysAgent
from crewai import Crew, Task

heavy = MitosysAgent(role="Heavy task specialist")
crew = Crew(agents=[heavy], tasks=[Task(description="...", agent=heavy)])
crew.kickoff()
```

```bash
pip install mitosys[crewai]
```

---

## CLI

The `mitosys` command is included with the package and makes the whole lifecycle visible in your terminal:

```bash
# Stream the live lifecycle (default)
mitosys run "Write a comprehensive analysis of renewable energy trends"

# Wait for the full result (no streaming)
mitosys run "..." --no-stream

# Pipe the raw JSON to jq
mitosys run "..." --json | jq '.final_answer'

# Check backend health
mitosys health

# Show version + configured URL
mitosys version
```

**Flags for `run`:**

| Flag | Description |
|------|-------------|
| `--url URL` | Override backend URL |
| `--no-stream` | Blocking POST /run (no live events) |
| `--json` | Raw JSON to stdout; lifecycle to stderr |
| `--timeout SEC` | HTTP timeout (default 120) |

---

## How It Works

1. Your task is sent to the Mitosys backend.
2. An **effort scorer** evaluates breadth × depth (1–10) and recommends how many agents to spawn.
3. The **parent agent** divides the task into sub-tasks.
4. Each **sub-agent** self-assesses its sub-task. If it's too complex, it proposes recursive division.
5. The **regulator** (parent LLM) approves or denies each proposal — keeping the tree bounded.
6. Approved sub-agents spawn children; all leaf agents execute concurrently.
7. Results are collected, agents are destroyed, and the parent **synthesizes** a final answer.

- Backend repo: [github.com/NorthCommits/mitosys-backend](https://github.com/NorthCommits/mitosys-backend)
- Live backend: [lumidoc-mitosys-backend.hf.space](https://lumidoc-mitosys-backend.hf.space)

---

## What's New in v0.3.0

- **SDK-first** — `import mitosys` is now the primary interface; the CLI is one entry point among many.
- **Typed result objects** — `MitosysResult`, `AgentTree`, `EffortScore`, `SubTask`, `SubResult` with autocomplete-friendly properties.
- **Typed event stream** — `MitosysEvent` with `.score`, `.agent`, `.final_answer`, etc.
- **Framework adapters** — AutoGen, LangGraph, CrewAI (optional extras).
- **Typed exceptions** — `MitosysNetworkError`, `MitosysBackendError`; no httpx leakage.
- Package renamed from `mitosys-cli` → `mitosys`.

## What's New in v0.2.0

- Effort scoring, recursive division, regulator approval, agent tree — see [CHANGELOG](CHANGELOG.md).

---

## Roadmap

- Rate limiting and concurrency controls
- More framework adapters (LlamaIndex, Semantic Kernel, Haystack)
- Self-hosted deployment guide
- Streaming progress callback API (non-async)
- Token usage reporting per agent

---

## Upgrading from 0.2.0

```bash
pip uninstall mitosys-cli
pip install mitosys
```

The `mitosys` CLI command is identical. Only the Python import path changes:

```python
# Before (v0.2.0)
from mitosys_cli.cli import app

# After (v0.3.0)
from mitosys.cli.main import app
```

---

## License

MIT — see [LICENSE](LICENSE).

## Author

Built by **Swapnil Bhattacharya**, part of [NorthCommits](https://github.com/NorthCommits).
