Inspiration
I work as a data scientist, and a big part of my job is classification work. Over the last couple of years that increasingly means using LLMs as classifiers: label a few hundred thousand support tickets, comments, transactions, whatever. It runs offline, nobody is waiting on a response, and it adds up to real money. Batch APIs exist for exactly this, and providers price them at up to 50% below synchronous calls. I knew this, and I still barely used them, because every provider has its own upload protocol, polling model, and result format, and I could never justify the integration work for a one-off job.
Then I came across a package by Hayden Bleasel, a unified batch SDK in TypeScript. I loved the idea immediately and could not use it at all, because almost everything we share at work is Python. That gap annoyed me enough to build the Python version myself, and to push it further than the original: a fully typed async library, plus a proper CLI, plus an Agent Skill, so that coding agents can use it too. The end state I wanted was simple. Next time a classification job lands on my desk, I just ask Codex to run it through Batchwork and it costs half as much.
What it does
- Typed async Python API: submit text, embedding, or image batches with
provider/modelstrings, and get back normalized jobs, results, usage, and errors correlated bycustom_id, across OpenAI, Anthropic, Google Gemini, Groq, Mistral, Together AI, and xAI. Stores, pollers, and signed webhooks for production pipelines. batchworkCLI:submit,run,status,wait,results,cancelfrom any terminal. Human output when interactive, versioned JSON/JSONL when piped, a local job registry with aliases, a documented exit-code catalog, and spend guardrails.- Agent Skill:
npx skills add ajanraj/batchwork-ai@batchwork-aiteaches a coding agent the CLI contract, including when to ask before spending money and how to resume interrupted jobs.
How I built it, with Codex and GPT-5.6
This is a solo project, and honestly Codex was the second pair of hands. Everything here, the library, the CLI, the agent skill, the tests, the docs site, and the release pipeline, was built in the Codex CLI with GPT-5.6-sol (with GPT-5.6-luna and terra subagents) inside the submission period: first session July 15, first PyPI release July 18.
- Plan. Codex explored Hayden's TypeScript package with three parallel subagents, then ran a structured interview where it grilled me on every design decision before writing a line of code.
- Implement. GPT-5.6-sol built seven provider adapters across three modalities, keeping the core provider-neutral and isolating every vendor quirk in its adapter.
- Harden. Repeated review loops caught real P1 security issues that Codex then fixed: SSRF protection on media downloads, Together's presigned upload protocol, credential leaks on borrowed HTTP clients, webhook retry semantics.
- Verify live. Codex ran a 300-request spam-classification evaluation against the real OpenAI Batch API (90.3% accuracy, about $0.007), then reproduced it from a clean project installing only the published wheel. That test is my actual day job in miniature, and it cost less than a cent.
- Ship. Codex drove PyPI trusted publishing and the docs deployment. When a gzip decoding bug surfaced during demo prep, Codex diagnosed it from a stack trace, fixed it with a regression test, and cut a patch release within the hour.
Challenges
The TypeScript original had it easier than I expected. It sits on top of the AI SDK, which already abstracts a lot of the cross-provider mess. Python has no equivalent for batch work, so there was no layer to lean on. Every provider protocol had to be handled by hand: OpenAI's file uploads, Together's presigned upload flow, Google's inline result containers, Anthropic's result streaming, seven different status vocabularies and usage formats. I say "by hand" but I really mean Codex did it, adapter by adapter, while keeping the core provider-neutral so none of that mess leaks into the API.
Security was the other one. Batch tooling downloads remote media and follows provider URLs, so SSRF pinning, redirect revalidation, and credential hygiene had to be built in from the start.
What I learned
Mostly that my bottleneck was tokens, not skill or time. This took about five days of sessions around a day job. With a Pro 200x plan, or if I worked at OpenAI with unlimited tokens, I genuinely think this would have been a one-day project, because Codex was never the slow part. I was, waiting on rate limits and reviewing between sessions.
The other lesson: building the tool agent-first paid off immediately. The first real user of the Agent Skill was Codex itself, running the classification demo that started this whole thing.
Log in or sign up for Devpost to join the conversation.