Metadata-Version: 2.5
Name: pyvello
Version: 0.1.3
Summary: A Python-First Reactive AI UI Framework with React, shadcn/ui and Automatic Agent Swarm DAGs
Project-URL: Homepage, https://pyvello.dev
Project-URL: Documentation, https://pyvello.dev/docs
Project-URL: Repository, https://github.com/pyvello/pyvello
Author: Pyvello Contributors
License: MIT
Keywords: agents,ai,fastapi,fullstack,litellm,react,reactive,shadcn,ui,websocket
Classifier: Development Status :: 4 - Beta
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: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: User Interfaces
Requires-Python: >=3.10
Requires-Dist: click>=8.1.0
Requires-Dist: fastapi>=0.110.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: litellm>=1.0.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pypdf>=6.21.4
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: reportlab>=5.1.0
Requires-Dist: rich>=13.0.0
Requires-Dist: uvicorn[standard]>=0.28.0
Requires-Dist: watchfiles>=0.21.0
Requires-Dist: websockets>=12.0
Provides-Extra: dev
Requires-Dist: build>=1.0.0; extra == 'dev'
Requires-Dist: httpx>=0.27.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: twine>=5.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# Pyvello

**A Python-First Reactive AI UI Framework with React 18, shadcn/ui, LiteLLM Agent Swarms, and Automatic Graph Visualization**

Write pure Python. Get an enterprise-grade React 18 UI with Tailwind CSS and Radix UI primitives. Build autonomous multi-agent swarms with LiteLLM, attach tools (RAG, SQL, Sheets, Gmail), connect self-hosted inference clusters (vLLM, Ollama), and observe execution in real-time over persistent WebSockets.

---

## Features

- **Python-First Simplicity**: Build full web applications without writing React, JSX, or CSS.
- **shadcn/ui & 18 Calibrated Palettes**: Coherent design tokens, dark and light modes, accessible Radix UI primitives, clean typography.
- **LiteLLM Multi-Agent Swarms**: Implement all 6 Anthropic patterns (*Prompt Chaining, Routing, Parallelization, Orchestrator-Workers, Evaluator-Optimizer, and Autonomous Multi-Tool*) across 100+ models.
- **Custom Inference Base URLs**: Route requests to self-hosted vLLM clusters (`http://localhost:8000/v1`), local Ollama (`http://localhost:11434/v1`), LM Studio, or OpenRouter via `api_base`.
- **Builtin Enterprise Tools**: Out-of-the-box, fully runnable tools for RAG vector search, relational SQL databases, Google Sheets sync, and Gmail dispatch.
- **Universal API Client (`pyvello.api`)**: Axios-style REST client, SSE streaming, and WebSockets with automatic component loading state orchestration (`with api.loading(btn, card): ...`).
- **Real-Time Agent Graph Visualization**: Live interactive canvas powered by `@xyflow/react` and Dagre auto-layout. Watch nodes execute with live duration tracking, token telemetry, and slide-over inspectors.
- **Production DataTable**: Sorting, global search, pagination, and 3-dots action menus with conditional visibility rules.
- **Interactive SVG Charts**: Area charts, bar charts, line charts, and donut charts with responsive tooltips.
- **Zero-Node Runtime with Instant Hot Reloading**: Production React bundle is packaged directly inside the Python wheel. Hot reload is enabled by default for rapid local development.
- **Jupyter Notebook & Google Colab Support**: Embed responsive full-stack apps inline inside `.ipynb` cells via non-blocking background threads.
- **LangGraph-Style Conditional Tool Nodes**: Dedicated tool nodes connected with conditional call and result return edges, rendered on a full-screen canvas.

---

## Quickstart

### 1. Installation

```bash
pip install pyvello
```

*All dependencies (FastAPI, Uvicorn, LiteLLM, HTTPX, WebSockets, Pydantic, Watchfiles) install automatically.*

---

### 2. Autonomous Multi-Tool Agent (RAG, SQL, Sheets, Gmail)

```python
import pyvello as ui
from pyvello.tools import (
    query_knowledge_base,
    query_database,
    read_google_sheet,
    send_gmail_message,
)

# Initialize Agent with Tools, Model Switching, and Custom Base URL
agent = ui.agent(
    name="EnterpriseOpsAgent",
    model="gpt-4o",
    models=[
        {"id": "gpt-4o", "name": "GPT-4o (OpenAI)", "badge": "Cloud"},
        {"id": "claude-3-5-sonnet", "name": "Claude 3.5 Sonnet", "badge": "Coding"},
        {"id": "meta-llama/Llama-3.3-70B-Instruct", "name": "Llama 3.3 (Local vLLM)", "badge": "Local GPU"},
    ],
    system_prompt="You are an enterprise operations assistant. Use RAG for policies, SQL for DB queries, Sheets for CRM deals, and Gmail to dispatch summaries.",
    tools=[query_knowledge_base, query_database, read_google_sheet, send_gmail_message],
    temperature=0.2,
    api_base="http://localhost:8000/v1",  # Self-hosted vLLM / Ollama endpoint
)

# Launch interactive UI with one call
agent.to_app().launch()
```

---

### 3. Multi-Agent Swarm Orchestrator

```python
import pyvello as ui

# 1. Specialized Worker Subagents
market_worker = ui.agent(name="MarketResearcher", system_prompt="Analyze target addressable market and unit economics.")
infra_worker = ui.agent(name="InfraArchitect", system_prompt="Specify cloud infrastructure and multi-region Kubernetes nodes.")
risk_worker = ui.agent(name="RiskAssessor", system_prompt="Evaluate compliance, HIPAA guidelines, and operational risk.")

# 2. Dynamic Swarm Orchestrator with Supervisor System Prompt & Model Selection
orchestrator = ui.orchestrator(
    agents=[market_worker, infra_worker, risk_worker],
    supervisor_system_prompt="You are an enterprise software architect supervising junior engineers. Decompose goals and synthesize verified deliverables.",
    supervisor_model="gpt-4o",
    models=[
        {"id": "gpt-4o", "name": "GPT-4o (Supervisor)", "badge": "Cloud"},
        {"id": "claude-3-5-sonnet", "name": "Claude 3.5 Sonnet", "badge": "Coding"},
        {"id": "meta-llama/Llama-3.3-70B-Instruct", "name": "Llama 3.3 (vLLM :8000)", "badge": "Local GPU"},
    ],
    temperature=0.2,
    stream=True,
    structured_output={"type": "json_object"},
    api_base="http://localhost:8000/v1",  # Cascades to workers automatically!
)

# 3. Mount in Reactive Chat UI
orchestrator.to_app().launch()
```

---

### 4. Universal API Client & Automatic Loading States

```python
from pyvello import api, ui

client = api.ApiClient(base_url="https://api.mycompany.org/v1")

with ui.App("Telemetry Dashboard"):
    m1 = ui.metric("Active Sessions", "14,280")
    btn = ui.button("Sync Telemetry", icon="RefreshCw", loader_style="spinner")

    # Automatically sets button loading=True, renders spinner, and restores on complete
    @btn.on("click")
    def on_sync():
        with api.loading(btn, m1):
            res = client.get("/telemetry/metrics")
            ui.update(m1, value=res.json()["active_sessions"])
            ui.toast("Metrics synchronized!", "success")
```

---

### 5. Custom Tools with Automatic JSON Schema Extraction

```python
import pyvello as ui

@ui.tool(description="Calculate portfolio Sharpe ratio given returns and risk-free rate")
def calculate_sharpe(returns: list[float], risk_free_rate: float = 0.04) -> float:
    mean_ret = sum(returns) / len(returns)
    variance = sum((r - mean_ret) ** 2 for r in returns) / len(returns)
    std_dev = variance ** 0.5
    return (mean_ret - risk_free_rate) / std_dev if std_dev > 0 else 0.0

agent = ui.agent(
    name="PortfolioAnalyst",
    tools=[calculate_sharpe],
    model="gpt-4o"
)
```

---

## All 6 Agent Architecture Patterns Supported

| Pattern | Class / Function | Description |
| :--- | :--- | :--- |
| **1. Autonomous Multi-Tool** | `ui.agent(tools=[...])` | Dynamic tool calling loop with automatic progress & result cards. |
| **2. Prompt Chaining** | `ui.chain(steps=[...])` | Sequential LLM pipeline with programmatic validation gates. |
| **3. Routing / Intent Agent** | `ui.router(routes={...})` | Semantic intent classification and specialist handoff. |
| **4. Parallelization** | `ui.parallel(mode="sectioning" \| "voting")` | Concurrent subtask sectioning or majority voting consensus. |
| **5. Orchestrator-Workers** | `ui.orchestrator(agents=[...])` | Dynamic task decomposition with configurable supervisor prompt. |
| **6. Evaluator-Optimizer** | `ui.judge(rubric=..., threshold=4.0)` | LLM-as-Judge scorecard evaluation with automated self-correction. |

---

## 18 Calibrated Theme Palettes

Red (`palette="red"`) is configured as the framework default theme palette. You can pass any of the 18 calibrated theme palettes to `ui.App`, `ui.ChatInterface`, or `agent.to_app()`:

`red` (default), `rose`, `violet`, `indigo`, `blue`, `sky`, `cyan`, `teal`, `emerald`, `green`, `yellow`, `amber`, `orange`, `zinc`, `slate`, `stone`, `gray`, `neutral`.

Toggle dark and light modes with persistent client preference syncing.

---

## CLI & Notebook Reference

```bash
# Start local dev server (Hot reload enabled by default)
pyvello run app.py

# Specify port or disable reload if needed
pyvello run app.py --port 8000 --no-reload

# Export application to a standalone React 18 + Vite 5 project
pyvello export app.py --output dist/
```

### Jupyter Notebook (.ipynb) Inline Embedding

```python
import pyvello as ui

agent = ui.agent(name="Analyst", system_prompt="You are a data analyst.")

# Embeds directly into the notebook output cell without blocking kernel:
agent.to_app().launch(inline=True, height=750)
```

---

## License

MIT License.
