Operonx

Operonx is a Python workflow engine whose ops can yield. The same graph runs as a batch job over a file, as a streaming pipeline (a voice bot: audio → STT → LLM → TTS), or behind an HTTP or WebSocket service.

You build with it through a coding assistant (Claude Code, Codex, Cursor, …). operonx init makes a project the assistant can work in at once: a layout, a first feature with its tests, the project's rules in AGENTS.md, and the API guide of your installed operonx beside the code.

Start a project

With uv:

uvx operonx init myapp     # uvx runs operonx without installing it
cd myapp
uv sync
uv run pytest              # the first feature's tests, offline

With pip only (no uv, e.g. behind a company mirror):

pip install operonx
operonx init myapp
cd myapp
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -e ".[test]"
pytest

operonx init writes the commands of the toolchain you use into the project's docs: uv when it is installed, else pip (--uv or --pip to choose). The first feature is --template hello (pure compute, a job and an HTTP service), http, chat (one LLM call) or agent (an agent with a tool).

Then open the folder in your coding assistant and ask for what you want: "add a feature that scores each call in datasets/calls.jsonl with the assistant model, and a job that runs it nightly".

What you get

myapp/
├── AGENTS.md            the rules your assistant reads first (CLAUDE.md is `@AGENTS.md`)
├── .operonx/guide/      the operonx API guide, for the version installed here
├── app/main.py          the map: every service and job, in one Application
├── src/greeting/        one feature, one folder
│   ├── graph.py         the wiring: which op runs after which, what feeds what
│   └── ops.py           the logic: plain Python functions
├── tests/               the feature's tests; no test calls a real model
├── datasets/            what jobs run over (.jsonl)
├── resources.yaml       models and stores, by key (`llm:assistant`)
├── .env.example         the secrets resources.yaml names; copy to .env
├── operonx.toml         points the operonx command at app/main.py
├── pyproject.toml       works with uv and with pip
└── docs/brd/            the requirements and their checklist (`--no-brd` skips it)

What your assistant reads

docs/brd/ is the project's living BRD: a checklist with one row per requirement, its status, and the test that proves it. The assistant keeps the rows true as it changes code. operonx-project builds the open rows as milestones of cards on a board (docs/brd/board/), with coding agents, review and held-out tests. The studio's Board tab is where you run it and answer its questions, or tell its assistant what to build (packages/operonx-project/).

AGENTS.md tells the assistant to read the guide before it uses an operonx API, so it does not write operonx from memory or from an older version. The marked blocks in AGENTS.md (<!-- operonx:guide -->, <!-- operonx:commands -->, <!-- operonx:builder -->) belong to operonx; the rest is yours.

After an upgrade, operonx guide refreshes the guide and that block. Any operonx command run in the project notices a stale guide and refreshes it.

uv lock --upgrade-package operonx && uv sync && uv run operonx guide   # uv
pip install -U operonx && operonx guide                                # pip

Run it, serve it, see it

uv run operonx run greet_people   # a job: the graph once per line of datasets/people.jsonl
uv run operonx serve              # the services: POST /greet on :8000
uv run operonx studio             # the project in operonx-studio, in the browser

With pip, the same commands without uv run, in the activated .venv.

operonx-studio draws every graph (what runs after what, and which value goes where), lets you talk to a service turn by turn, and shows runs, evals, jobs and services. It is a separate tool, installed once from its repository:

git clone https://github.com/batman1m2001-cyber/operonx-studio
operonx-studio/install.sh            # or, without bash: pip install ./operonx-studio

What the code looks like

An op is a Python function. One that yields runs what follows it once per item. A @graph wires ops with >>:

from operonx import END, START, graph, op


@op
def words(text: str):
    for w in text.split():
        yield {"word": w}


@op
def shout(word: str) -> dict:
    return {"loud": word.upper()}


@graph
def flow(text):
    w = words(text=text)
    s = shout(word=w["word"])
    START >> w >> s >> END

app/main.py decides how a graph runs: a Job over a file, or a Service behind http(...), websocket(...), webhook(...) or schedule(...).

Extras

Provider SDKs are extras. A project names its extras on the operonx[...] line of pyproject.toml (init writes operonx[serve]); add one there, e.g. operonx[serve,openai], then uv sync (with pip, pip install -e ".[test]").

operonx-agents (agents) and operonx-kb (knowledge bases) are separate packages; each adds its own pages to .operonx/guide/.

Documentation

Contributing

git clone https://github.com/batman1m2001-cyber/Operonx.git
cd Operonx
uv sync --all-extras
pre-commit install
uv run pytest tests/ -m "not integration"

See CONTRIBUTING.md for the full contributor guide.

License

Apache 2.0