cowo 0.1.0__tar.gz

cowo-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 yaitso
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS 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.

cowo-0.1.0/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.4
+Name: cowo
+Version: 0.1.0
+Summary: codex workflows — multi-agent orchestration over the codex app-server: fan out, pipeline, and build DAGs of agents
+Keywords: llm,codex,agents,orchestration,workflows,cowo
+Author: yaitso
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3
+Classifier: Development Status :: 3 - Alpha
+Classifier: Typing :: Typed
+Requires-Dist: cyclopts>=4.18.0
+Requires-Dist: openai-codex>=0.1.0b2
+Requires-Dist: pydantic>=2.13.4
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/yaitso/cowo
+Project-URL: Repository, https://github.com/yaitso/cowo
+Description-Content-Type: text/markdown
+
+# cowo
+
+multi-agent orchestration for python, built on the official [codex app-server](https://developers.openai.com/codex/app-server). fan out, pipeline, and compose **DAGs of agents** — each agent is a full codex thread (tools, sandbox, structured output), not a bare completion — all multiplexed over one long-lived process.
+
+## why
+
+the codex app-server already gives you threads, forking, mailboxes, structured output, and a whole agent-graph runtime — but its python SDK is a *single-client driver*. it has no conductor: no fan-out, no DAG, no tunable concurrency, no token budgeting across agents. `cowo` is that conductor.
+
+- **`agent()`** — one codex thread, one turn, structured result. the leaf primitive.
+- **`parallel` / `pipeline`** — imperative fan-out / staged flows.
+- **`dag` + `task` + `>>`** — declarative agent graphs (airflow-style operators) scheduled over a **tunable concurrency** limiter — drain thousands of queued agents through N live-adjustable slots.
+- **`session`** — a persistent multi-turn agent (a codex thread that remembers).
+- **pydantic-native** — pass a `BaseModel` as the schema, get a validated instance back.
+- **one process** — N agents = N threads multiplexed over a single app-server, not N subprocesses.
+
+## install
+
+```sh
+uv add cowo          # distribution name; you still `import cowo`
+```
+
+the [`openai-codex`](https://pypi.org/project/openai-codex/) SDK (a dependency) bundles the codex binary — no separate install. you do need codex auth once:
+
+```sh
+codex login        # or set OPENAI_API_KEY
+cowo doctor
+```
+
+## quickstart
+
+```python
+import asyncio
+from pydantic import BaseModel
+from cowo import agent, parallel, spent
+
+class Fact(BaseModel):
+    name: str
+    year: int
+
+async def main():
+    answer = await agent("Reply with one word: pong")
+    fact = await agent("Founding year of Tokyo.", schema=Fact)   # -> Fact(name='Tokyo', year=1457)
+    cities = await parallel([
+        (lambda c=c: agent(f"Capital of {c}? one word")) for c in ("France", "Japan")
+    ])
+    print(answer, fact, cities, "tokens:", spent.spent())
+
+asyncio.run(main())
+```
+
+structured output is enforced by the app-server (`outputSchema`) — a schema'd agent can't return non-conforming JSON.
+
+## DAGs of agents
+
+declare the graph with airflow-style `>>`; the scheduler runs it over a concurrency limiter:
+
+```python
+from cowo import dag, task
+
+a = task("Analyze module A.")
+b = task("Analyze module B.")
+synth = task(lambda ups: f"Synthesize these analyses:\n{ups}")
+
+[a, b] >> synth                          # a, b run concurrently; synth gets their results
+result = dag(synth).run(concurrency=8)   # drain the graph through 8 slots
+```
+
+the DAG is explicit data before it runs — inspectable, schedulable, journalable. concurrency is live-adjustable (`d.concurrency = 32`) for draining large queues.
+
+## recursion
+
+recursion isn't a primitive — it's a recursive python function whose leaves are `agent()` calls:
+
+```python
+async def summarize(chunks):
+    if len(chunks) == 1:
+        return await agent(f"Summarize:\n{chunks[0]}")
+    mid = len(chunks) // 2
+    parts = await parallel([(lambda h=h: summarize(h)) for h in (chunks[:mid], chunks[mid:])])
+    return await agent("Merge these summaries:\n" + "\n".join(parts))
+```
+
+## api
+
+- `agent(prompt, *, schema=None, model=None, effort=None, sandbox=None, cwd=None, label=None)` — one-shot agent (ephemeral thread). `schema` accepts a dict JSON Schema or a pydantic `BaseModel`. `sandbox=None` is yolo (full access, no approvals); pass `"read-only"`/`"workspace-write"` to restrict.
+- `session(*, model=None, sandbox=None, cwd=None)` — `.send(prompt, schema=, effort=)`, a persistent thread across turns.
+- `parallel(thunks)` / `pipeline(items, *stages)` — imperative fan-out / staged flow.
+- `dag(*terminals).run(concurrency=N)` + `task(...)` + `>>` — declarative agent DAG.
+- `spent` — `budget` with `.spent()` / `.remaining()` / `.total`, aggregated across all agents.
+- `run(coro)` — `asyncio.run` that also closes the shared app-server.
+- `COWO_CONCURRENCY` env — default global concurrency cap (`min(16, cpu-2)`).
+
+## roadmap
+
+codex ships a full actor runtime (`multi_agents_v2`: spawn/send/wait/close over a tree of threads with mailboxes and supervision). v0.2 will expose the **actor substrate** — message-passing "soup of agents", cyclic feedback (critic ⇄ generator), and `let-it-crash` supervision — with `dag`/`parallel`/`pipeline` re-expressed as topologies over it. see [ACTORS.md](ACTORS.md).
+
+## license
+
+MIT

cowo-0.1.0/README.md

@@ -0,0 +1,99 @@
+# cowo
+
+multi-agent orchestration for python, built on the official [codex app-server](https://developers.openai.com/codex/app-server). fan out, pipeline, and compose **DAGs of agents** — each agent is a full codex thread (tools, sandbox, structured output), not a bare completion — all multiplexed over one long-lived process.
+
+## why
+
+the codex app-server already gives you threads, forking, mailboxes, structured output, and a whole agent-graph runtime — but its python SDK is a *single-client driver*. it has no conductor: no fan-out, no DAG, no tunable concurrency, no token budgeting across agents. `cowo` is that conductor.
+
+- **`agent()`** — one codex thread, one turn, structured result. the leaf primitive.
+- **`parallel` / `pipeline`** — imperative fan-out / staged flows.
+- **`dag` + `task` + `>>`** — declarative agent graphs (airflow-style operators) scheduled over a **tunable concurrency** limiter — drain thousands of queued agents through N live-adjustable slots.
+- **`session`** — a persistent multi-turn agent (a codex thread that remembers).
+- **pydantic-native** — pass a `BaseModel` as the schema, get a validated instance back.
+- **one process** — N agents = N threads multiplexed over a single app-server, not N subprocesses.
+
+## install
+
+```sh
+uv add cowo          # distribution name; you still `import cowo`
+```
+
+the [`openai-codex`](https://pypi.org/project/openai-codex/) SDK (a dependency) bundles the codex binary — no separate install. you do need codex auth once:
+
+```sh
+codex login        # or set OPENAI_API_KEY
+cowo doctor
+```
+
+## quickstart
+
+```python
+import asyncio
+from pydantic import BaseModel
+from cowo import agent, parallel, spent
+
+class Fact(BaseModel):
+    name: str
+    year: int
+
+async def main():
+    answer = await agent("Reply with one word: pong")
+    fact = await agent("Founding year of Tokyo.", schema=Fact)   # -> Fact(name='Tokyo', year=1457)
+    cities = await parallel([
+        (lambda c=c: agent(f"Capital of {c}? one word")) for c in ("France", "Japan")
+    ])
+    print(answer, fact, cities, "tokens:", spent.spent())
+
+asyncio.run(main())
+```
+
+structured output is enforced by the app-server (`outputSchema`) — a schema'd agent can't return non-conforming JSON.
+
+## DAGs of agents
+
+declare the graph with airflow-style `>>`; the scheduler runs it over a concurrency limiter:
+
+```python
+from cowo import dag, task
+
+a = task("Analyze module A.")
+b = task("Analyze module B.")
+synth = task(lambda ups: f"Synthesize these analyses:\n{ups}")
+
+[a, b] >> synth                          # a, b run concurrently; synth gets their results
+result = dag(synth).run(concurrency=8)   # drain the graph through 8 slots
+```
+
+the DAG is explicit data before it runs — inspectable, schedulable, journalable. concurrency is live-adjustable (`d.concurrency = 32`) for draining large queues.
+
+## recursion
+
+recursion isn't a primitive — it's a recursive python function whose leaves are `agent()` calls:
+
+```python
+async def summarize(chunks):
+    if len(chunks) == 1:
+        return await agent(f"Summarize:\n{chunks[0]}")
+    mid = len(chunks) // 2
+    parts = await parallel([(lambda h=h: summarize(h)) for h in (chunks[:mid], chunks[mid:])])
+    return await agent("Merge these summaries:\n" + "\n".join(parts))
+```
+
+## api
+
+- `agent(prompt, *, schema=None, model=None, effort=None, sandbox=None, cwd=None, label=None)` — one-shot agent (ephemeral thread). `schema` accepts a dict JSON Schema or a pydantic `BaseModel`. `sandbox=None` is yolo (full access, no approvals); pass `"read-only"`/`"workspace-write"` to restrict.
+- `session(*, model=None, sandbox=None, cwd=None)` — `.send(prompt, schema=, effort=)`, a persistent thread across turns.
+- `parallel(thunks)` / `pipeline(items, *stages)` — imperative fan-out / staged flow.
+- `dag(*terminals).run(concurrency=N)` + `task(...)` + `>>` — declarative agent DAG.
+- `spent` — `budget` with `.spent()` / `.remaining()` / `.total`, aggregated across all agents.
+- `run(coro)` — `asyncio.run` that also closes the shared app-server.
+- `COWO_CONCURRENCY` env — default global concurrency cap (`min(16, cpu-2)`).
+
+## roadmap
+
+codex ships a full actor runtime (`multi_agents_v2`: spawn/send/wait/close over a tree of threads with mailboxes and supervision). v0.2 will expose the **actor substrate** — message-passing "soup of agents", cyclic feedback (critic ⇄ generator), and `let-it-crash` supervision — with `dag`/`parallel`/`pipeline` re-expressed as topologies over it. see [ACTORS.md](ACTORS.md).
+
+## license
+
+MIT

cowo-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["uv_build>=0.8,<0.12"]
+build-backend = "uv_build"
+
+[project]
+name = "cowo"
+version = "0.1.0"
+description = "codex workflows — multi-agent orchestration over the codex app-server: fan out, pipeline, and build DAGs of agents"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "yaitso" }]
+keywords = ["llm", "codex", "agents", "orchestration", "workflows", "cowo"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Development Status :: 3 - Alpha",
+    "Typing :: Typed",
+]
+dependencies = [
+    "cyclopts>=4.18.0",
+    "openai-codex>=0.1.0b2",
+    "pydantic>=2.13.4",
+]
+
+[project.scripts]
+cowo = "cowo.cli:cli"
+
+[project.urls]
+Homepage = "https://github.com/yaitso/cowo"
+Repository = "https://github.com/yaitso/cowo"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.0",
+]

cowo-0.1.0/src/cowo/__init__.py

@@ -0,0 +1,16 @@
+from cowo.core import agent, budget, log, parallel, phase, pipeline, run, session, spent
+from cowo.graph import dag, task
+
+__all__ = [
+    "run",
+    "log",
+    "dag",
+    "task",
+    "agent",
+    "phase",
+    "spent",
+    "budget",
+    "session",
+    "parallel",
+    "pipeline",
+]

cowo-0.1.0/src/cowo/cli.py

@@ -0,0 +1,40 @@
+import json
+
+import cyclopts
+
+from cowo.core import agent, run
+
+cli = cyclopts.App(
+    name="cowo",
+    help="codex workflows — multi-agent orchestration over the codex app-server",
+)
+
+
+@cli.command
+def doctor():
+    """verify the codex app-server backend is reachable and authenticated."""
+    try:
+        reply = run(agent("Reply with the single word: ok"))
+    except Exception as e:
+        print(f"backend error: {e}")
+        print("hint: authenticate with `codex login` or set OPENAI_API_KEY")
+        raise SystemExit(1) from e
+    print(
+        f"backend ok: {reply!r}"
+        if reply
+        else "backend returned nothing — run `codex login`"
+    )
+
+
+@cli.command
+def ask(
+    prompt: str,
+    *,
+    schema: str | None = None,
+    model: str | None = None,
+    effort: str | None = None,
+):
+    """one-shot agent call; --schema PATH forces structured json output."""
+    spec = json.loads(open(schema).read()) if schema else None
+    out = run(agent(prompt, schema=spec, model=model, effort=effort))
+    print(json.dumps(out, indent=2) if isinstance(out, (dict, list)) else out)

cowo-0.1.0/src/cowo/core.py

@@ -0,0 +1,198 @@
+import asyncio
+import json
+import os
+from collections.abc import Awaitable, Callable, Iterable
+from dataclasses import dataclass
+
+from openai_codex import ApprovalMode, AsyncCodex, Sandbox
+from pydantic import BaseModel
+
+type schema = dict | type[BaseModel]
+type result = str | dict | list | BaseModel | None
+
+CAP = max(1, min(16, (os.cpu_count() or 4) - 2))
+gate = asyncio.Semaphore(int(os.environ.get("COWO_CONCURRENCY", CAP)))
+
+SANDBOX = {
+    None: Sandbox.full_access,
+    "read-only": Sandbox.read_only,
+    "workspace-write": Sandbox.workspace_write,
+    "danger-full-access": Sandbox.full_access,
+    "full-access": Sandbox.full_access,
+}
+
+live: AsyncCodex | None = None
+opening = asyncio.Lock()
+
+
+async def codex() -> AsyncCodex:
+    global live
+    if live is None:
+        async with opening:
+            if live is None:
+                client = AsyncCodex()
+                await client.__aenter__()
+                live = client
+    return live
+
+
+async def shutdown() -> None:
+    global live
+    if live is not None:
+        await live.close()
+        live = None
+
+
+@dataclass
+class budget:
+    out: int = 0
+    total: int | None = None
+
+    def spend(self, n: int) -> None:
+        self.out += n
+
+    def spent(self) -> int:
+        return self.out
+
+    def remaining(self) -> float:
+        return float("inf") if self.total is None else max(0, self.total - self.out)
+
+
+spent = budget()
+
+
+def tokens(usage) -> int:
+    total = getattr(usage, "total", None)
+    return getattr(total, "output_tokens", 0) if total is not None else 0
+
+
+def log(msg: str) -> None:
+    print(f"  · {msg}", flush=True)
+
+
+def phase(title: str) -> None:
+    print(f"\n━━ {title} ━━", flush=True)
+
+
+def strictify(s: dict) -> dict:
+    if isinstance(s, dict):
+        if s.get("type") == "object":
+            s["additionalProperties"] = False
+            if "properties" in s:
+                s["required"] = list(s["properties"].keys())
+        for v in s.values():
+            strictify(v)
+    elif isinstance(s, list):
+        for v in s:
+            strictify(v)
+    return s
+
+
+def normalize(spec: schema | None) -> tuple[dict | None, type[BaseModel] | None]:
+    if spec is None:
+        return None, None
+    if isinstance(spec, type) and issubclass(spec, BaseModel):
+        return strictify(spec.model_json_schema()), spec
+    return spec, None
+
+
+def coerce(
+    final: str | None, spec: dict | None, model: type[BaseModel] | None
+) -> result:
+    if spec is None or not isinstance(final, str):
+        return final
+    try:
+        data = json.loads(final)
+    except json.JSONDecodeError:
+        return final
+    if model is not None:
+        try:
+            return model.model_validate(data)
+        except Exception:
+            return data
+    return data
+
+
+def cfg(effort: str | None) -> dict | None:
+    return {"model_reasoning_effort": effort} if effort else None
+
+
+async def agent(
+    prompt: str,
+    *,
+    schema: schema | None = None,
+    model: str | None = None,
+    effort: str | None = None,
+    sandbox: str | None = None,
+    cwd: str | None = None,
+    label: str | None = None,
+) -> result:
+    spec, model_cls = normalize(schema)
+    cx = await codex()
+    async with gate:
+        thread = await cx.thread_start(
+            model=model,
+            sandbox=SANDBOX[sandbox],
+            approval_mode=ApprovalMode.deny_all,
+            cwd=cwd,
+            ephemeral=True,
+            config=cfg(effort),
+        )
+        res = await thread.run(prompt, output_schema=spec)
+    spent.spend(tokens(res.usage))
+    return coerce(res.final_response, spec, model_cls)
+
+
+class session:
+    def __init__(
+        self,
+        *,
+        model: str | None = None,
+        sandbox: str | None = None,
+        cwd: str | None = None,
+    ):
+        self.model = model
+        self.sandbox = sandbox
+        self.cwd = cwd
+        self.thread = None
+
+    async def send(
+        self, prompt: str, *, schema: schema | None = None, effort: str | None = None
+    ) -> result:
+        spec, model_cls = normalize(schema)
+        cx = await codex()
+        if self.thread is None:
+            self.thread = await cx.thread_start(
+                model=self.model,
+                sandbox=SANDBOX[self.sandbox],
+                approval_mode=ApprovalMode.deny_all,
+                cwd=self.cwd,
+            )
+        async with gate:
+            res = await self.thread.run(prompt, output_schema=spec, effort=effort)
+        spent.spend(tokens(res.usage))
+        return coerce(res.final_response, spec, model_cls)
+
+
+async def parallel(thunks: Iterable[Callable[[], Awaitable]]) -> list:
+    return await asyncio.gather(*(t() for t in thunks))
+
+
+async def pipeline(items: Iterable, *stages: Callable[[result], Awaitable]) -> list:
+    async def chain(item):
+        value = item
+        for stage in stages:
+            value = await stage(value)
+        return value
+
+    return await asyncio.gather(*(chain(it) for it in items))
+
+
+def run(coro: Awaitable):
+    async def wrap():
+        try:
+            return await coro
+        finally:
+            await shutdown()
+
+    return asyncio.run(wrap())

cowo-0.1.0/src/cowo/graph.py

@@ -0,0 +1,142 @@
+import asyncio
+from collections.abc import Callable
+from graphlib import TopologicalSorter
+
+from cowo.core import agent, log, result, schema
+
+
+class limiter:
+    def __init__(self, limit: int | None):
+        self.limit = limit
+        self.active = 0
+        self.cond = asyncio.Condition()
+
+    async def __aenter__(self):
+        async with self.cond:
+            while self.limit is not None and self.active >= self.limit:
+                await self.cond.wait()
+            self.active += 1
+
+    async def __aexit__(self, *_):
+        async with self.cond:
+            self.active -= 1
+            self.cond.notify_all()
+
+    async def resize(self, limit: int | None):
+        async with self.cond:
+            self.limit = limit
+            self.cond.notify_all()
+
+
+class task:
+    def __init__(
+        self,
+        prompt: str | Callable[[list], str],
+        *,
+        schema: schema | None = None,
+        model: str | None = None,
+        effort: str | None = None,
+        sandbox: str | None = None,
+        cwd: str | None = None,
+        label: str | None = None,
+    ):
+        self.prompt = prompt
+        self.kw = dict(
+            schema=schema,
+            model=model,
+            effort=effort,
+            sandbox=sandbox,
+            cwd=cwd,
+            label=label,
+        )
+        self.deps: list[task] = []
+        self.result: result = None
+
+    def __rshift__(self, other: "task | list[task]"):
+        for t in other if isinstance(other, (list, tuple)) else [other]:
+            t.deps.append(self)
+        return other
+
+    def __rrshift__(self, others: "list[task]"):
+        for o in others:
+            self.deps.append(o)
+        return self
+
+    async def fire(self):
+        ups = [d.result for d in self.deps]
+        text = self.prompt(ups) if callable(self.prompt) else self.prompt
+        self.result = await agent(text, **self.kw)
+        return self
+
+
+def reach(terminals: list[task]) -> list[task]:
+    seen, stack = {}, list(terminals)
+    while stack:
+        n = stack.pop()
+        if id(n) in seen:
+            continue
+        seen[id(n)] = n
+        stack.extend(n.deps)
+    return list(seen.values())
+
+
+class dag:
+    def __init__(self, *terminals: task, concurrency: int | None = None):
+        self.terminals = list(terminals)
+        self.lim = limiter(concurrency)
+
+    @property
+    def concurrency(self) -> int | None:
+        return self.lim.limit
+
+    @concurrency.setter
+    def concurrency(self, n: int | None):
+        self.lim.limit = n
+
+    async def adjust(self, n: int | None):
+        await self.lim.resize(n)
+
+    async def arun(self) -> dict[task, result] | result:
+        nodes = reach(self.terminals)
+        ts = TopologicalSorter()
+        for n in nodes:
+            ts.add(n, *n.deps)
+        ts.prepare()
+        inflight: dict[int, asyncio.Task] = {}
+
+        async def gated(n: task):
+            async with self.lim:
+                return await n.fire()
+
+        while ts.is_active():
+            for n in ts.get_ready():
+                inflight[id(n)] = asyncio.create_task(gated(n))
+            done, _ = await asyncio.wait(
+                inflight.values(), return_when=asyncio.FIRST_COMPLETED
+            )
+            for t in done:
+                n = t.result()
+                ts.done(n)
+                del inflight[id(n)]
+                log(f"done {n.kw.get('label') or text_head(n)}")
+        if len(self.terminals) == 1:
+            return self.terminals[0].result
+        return {n: n.result for n in self.terminals}
+
+    def run(self, concurrency: int | None = None) -> dict[task, result] | result:
+        if concurrency is not None:
+            self.lim.limit = concurrency
+        from cowo.core import shutdown
+
+        async def wrap():
+            try:
+                return await self.arun()
+            finally:
+                await shutdown()
+
+        return asyncio.run(wrap())
+
+
+def text_head(n: task) -> str:
+    p = n.prompt if isinstance(n.prompt, str) else "<dynamic>"
+    return p[:40]