Metadata-Version: 2.4
Name: orcheo
Version: 0.23.0
Summary: Add your description here
License-File: LICENSE
Requires-Python: >=3.12
Requires-Dist: agentensor>=0.0.4
Requires-Dist: aiosqlite>=0.22.0
Requires-Dist: croniter>=2.0.0
Requires-Dist: cryptography>=43.0.1
Requires-Dist: dynaconf>=3.2.4
Requires-Dist: fastapi>=0.104.0
Requires-Dist: fastmcp>=2.13.0.2
Requires-Dist: feedparser>=6.0.11
Requires-Dist: httpx>=0.28.1
Requires-Dist: langchain-community>=0.0.10
Requires-Dist: langchain-google-genai>=3.0.0
Requires-Dist: langchain-mcp-adapters>=0.2.1
Requires-Dist: langchain-openai>=0.0.5
Requires-Dist: langchain>=1.1.3
Requires-Dist: langgraph-checkpoint-postgres>=3.0.0
Requires-Dist: langgraph-checkpoint-sqlite>=3.0.0
Requires-Dist: langgraph>=1.0.5
Requires-Dist: mcp[cli]>=1.12.0
Requires-Dist: motor>=3.6.0
Requires-Dist: openai-chatkit>=1.4.0
Requires-Dist: openai>=1.0.0
Requires-Dist: opentelemetry-api>=1.26.0
Requires-Dist: opentelemetry-exporter-otlp>=1.26.0
Requires-Dist: opentelemetry-sdk>=1.26.0
Requires-Dist: pinecone-text>=0.11.0
Requires-Dist: pinecone>=8.0.0
Requires-Dist: psycopg[binary,pool]>=3.2.0
Requires-Dist: py-mini-racer>=0.6.0
Requires-Dist: pycryptodome>=3.20.0
Requires-Dist: pydantic>=2.4.2
Requires-Dist: pymongo>=4.13.2
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: python-telegram-bot>=22.0
Requires-Dist: restrictedpython>=7.2
Requires-Dist: rouge-score>=0.1.2
Requires-Dist: sacrebleu>=2.3.0
Requires-Dist: selenium>=4.32.0
Requires-Dist: structlog>=24.4.0
Requires-Dist: uvicorn>=0.24.0
Requires-Dist: websockets>=12.0
Description-Content-Type: text/markdown

# Orcheo

[![CI](https://github.com/ShaojieJiang/orcheo/actions/workflows/ci.yml/badge.svg?event=push)](https://github.com/ShaojieJiang/orcheo/actions/workflows/ci.yml?query=branch%3Amain)
[![Coverage](https://coverage-badge.samuelcolvin.workers.dev/ShaojieJiang/orcheo.svg)](https://coverage-badge.samuelcolvin.workers.dev/redirect/ShaojieJiang/orcheo)
[![PyPI - Core](https://img.shields.io/pypi/v/orcheo.svg?logo=python&label=core)](https://pypi.org/project/orcheo/)
[![PyPI - Backend](https://img.shields.io/pypi/v/orcheo-backend.svg?logo=python&label=backend)](https://pypi.org/project/orcheo-backend/)
[![PyPI - SDK](https://img.shields.io/pypi/v/orcheo-sdk.svg?logo=python&label=sdk)](https://pypi.org/project/orcheo-sdk/)
[![PyPI - Agentensor](https://img.shields.io/pypi/v/agentensor.svg?logo=python&label=agentensor)](https://pypi.org/project/agentensor/)
[![npm - Canvas](https://img.shields.io/npm/v/orcheo-canvas.svg?logo=npm&label=canvas)](https://www.npmjs.com/package/orcheo-canvas)
[![GHCR - Stack](https://img.shields.io/badge/dynamic/xml?url=https%3A%2F%2Fghcr-badge.egpl.dev%2Fshaojiejiang%2Forcheo-stack%2Flatest_tag%3Fignore%3Dlatest&query=%2F%2F*%5Blocal-name()%3D%27g%27%5D%5Blast()%5D%2F*%5Blocal-name()%3D%27text%27%5D%5Blast()%5D&logo=docker&label=stack)](https://github.com/ShaojieJiang/orcheo/pkgs/container/orcheo-stack)
[![Documentation](https://readthedocs.org/projects/orcheo/badge/?version=latest)](https://orcheo.readthedocs.io/en/latest/)

Orcheo is a workflow orchestration platform designed for vibe coding — AI coding agents like Claude Code can start services, build workflows, and deploy them for you automatically. Read the [full documentation](https://orcheo.readthedocs.io/en/latest/) for guides, API reference, and examples.

> **Note:** This project is currently in Beta. Expect breaking changes as we iterate rapidly towards 1.0.

> **SIGIR Reviewers:** See the **[Conversational Search Examples](https://orcheo.readthedocs.io/en/latest/examples/conversational_search/)** for step-by-step demos from basic RAG to production-ready search.

## Why Orcheo?

- **Vibe-coding-first**: Already using Claude Code, Codex CLI, or Cursor? You **don't** need to learn Orcheo. Install the [agent skill](https://github.com/ShaojieJiang/agent-skills) and let your AI agent handle setup, workflow creation, and deployment.
- **Python-native**: Workflows are Python code powered by LangGraph — no proprietary DSL to learn.
- **Backend-first**: Run headless in production; the UI is optional.

## Quick Start

Use the installation path that matches your setup:

> Prerequisite: Docker Desktop/Engine must be installed to run the stack (`orcheo install --start-stack`).

<details open>
<summary>macOS / Linux</summary>

```bash
bash <(curl -fsSL https://ai-colleagues.com/install.sh)
```

</details>

<details>
<summary>Windows PowerShell</summary>

```powershell
irm https://ai-colleagues.com/install.ps1 | iex
```

</details>

<details>
<summary>SDK</summary>

```bash
uv tool install -U orcheo-sdk
orcheo install
```

</details>

<details>
<summary>macOS/Linux (non-interactive)</summary>

```bash
curl -fsSL https://ai-colleagues.com/install.sh | sh -s -- --yes --start-stack
```

</details>

<details>
<summary>Upgrade</summary>

```bash
orcheo install upgrade --yes
```

</details>

`orcheo install` syncs Docker stack assets into `~/.orcheo/stack` (or
`ORCHEO_STACK_DIR`), updates `.env` with setup-selected values, and can start the
stack with Docker Compose. Setup will prompt for
`VITE_ORCHEO_CHATKIT_DOMAIN_KEY`; you can skip it and continue, but ChatKit UI
features will stay disabled until you set a valid key.

The fastest way to get started with workflow building is still the **Agent Skill** approach.

> **Note:** Most AI coding agents (Claude Code, Codex CLI, Cursor) require a paid subscription. Free alternatives may exist but have not been tested with Orcheo.

### 1. Install the Orcheo Agent Skill

Add the [Orcheo agent skill](https://github.com/ShaojieJiang/agent-skills) to your AI coding agent (Claude Code, Cursor, etc.) by following the installation instructions in the repo.

### 2. Let Your Agent Do the Work

Once installed, simply ask your agent to:

- **Set up Orcheo**: "Set up Orcheo for local development"
- **Create workflows**: "Create a workflow that monitors RSS feeds and sends Slack notifications"
- **Deploy workflows**: "Deploy and schedule my workflow to run every hour"

Your AI agent will automatically:
- Install dependencies
- Start the backend server
- Create and configure workflows
- Handle authentication and deployment

That's it! Your agent handles the complexity while you focus on describing what you want your workflows to do.

## Guides

- **[Manual Setup Guide](https://orcheo.readthedocs.io/en/latest/manual_setup/)** — Installation, CLI reference, authentication, and Canvas setup
- **[Conversational Search Examples](https://orcheo.readthedocs.io/en/latest/examples/conversational_search/)** — Step-by-step demos from basic RAG to production-ready search

```bash
# Quick start: Run Demo 1 (no external services required)
uv sync --group examples
orcheo credential create openai_api_key --secret sk-your-key
python examples/conversational_search/demo_2_basic_rag/demo_2.py
```

## Reference

- **[SDK Reference](https://orcheo.readthedocs.io/en/latest/sdk_reference/)** — Python SDK for programmatic workflow execution
- **[Environment Variables](https://orcheo.readthedocs.io/en/latest/environment_variables/)** — Complete configuration reference

## For Developers

- **[Developer Guide](https://orcheo.readthedocs.io/en/latest/manual_setup/#developer-guide)** — Repository layout, development environment, and custom nodes
- **[Deployment Guide](https://orcheo.readthedocs.io/en/latest/deployment/)** — Docker Compose and PostgreSQL deployment recipes
- **[Custom Nodes and Tools](https://orcheo.readthedocs.io/en/latest/custom_nodes_and_tools/)** — Extend Orcheo with your own integrations

## Contributing

We welcome contributions from the community:

- **Share your extensions**: Custom nodes, agent tools, and workflows that extend Orcheo's capabilities. See the [Custom Nodes and Tools guide](https://orcheo.readthedocs.io/en/latest/custom_nodes_and_tools/) for how to create and load custom extensions.
- **How to contribute**: Open an [issue](https://github.com/ShaojieJiang/orcheo/issues), submit a [pull request](https://github.com/ShaojieJiang/orcheo/pulls), or start a [discussion](https://github.com/ShaojieJiang/orcheo/discussions). You can also publish and share your extensions independently for others to install.

## Citation

If you use Orcheo in your research, please cite it as:

```bibtex
@article{jiang2026orcheo,
  author       = {Jiang, Shaojie and Vakulenko, Svitlana and de Rijke, Maarten},
  title        = {Orcheo: A Modular Full-Stack Platform for Conversational Search},
  journal      = {arXiv preprint arXiv:2602.14710},
  year         = {2026}
}
```
