@endyai/atq 0.0.1

package/README.md

@@ -0,0 +1,109 @@
+# atq
+
+A task queue for agentic workloads.
+
+## The problem
+
+You have a large batch of tasks that need to be processed using an agent (language, reasoning, tool use tasks).
+
+Running these through a single long-lived agent doesn't work:
+
+- **Context bloat.** The agent accumulates results from previous tasks. Gets slower, more expensive, less focused.
+- **Fragile batching.** One failure midway can stall everything. Tracking what succeeded is painful.
+- **No concurrency.** Processing items one at a time when each task is independent is just slow.
+
+## The approach
+
+Each task gets its own fresh agent with a clean context. A pool of agents process items concurrently — one finishes, the next starts immediately.
+
+- **Fresh context per task.** Each agent only sees the item it's working on. Better focus, lower cost, no cross-contamination.
+- **Concurrent by default.** Control the pool size with `concurrency`.
+- **Stream results.** Results stream to stdout as agents complete.
+
+```mermaid
+graph LR
+  stdin["stdin (JSONL)"] --> atq
+  atq --> A1[Agent 1]
+  atq --> A2[Agent 2]
+  atq --> A3[Agent N]
+  A1 --> stdout["stdout (JSONL)"]
+  A2 --> stdout
+  A3 --> stdout
+```
+
+## CLI
+
+```bash
+cat companies.jsonl | atq -p "Normalize this company name. Return just the name." -c 10 -m claude-sonnet-4-6
+```
+
+Input is piped via stdin (one JSON object per line):
+```jsonl
+{"name": "Google LLC"}
+{"name": "APPLE INC."}
+{"name": "Meta Platforms, Inc."}
+```
+
+**Output** (stdout, one JSON line per completed item):
+```jsonl
+{"item":{"name":"Google LLC"},"output":"Google"}
+{"item":{"name":"APPLE INC."},"output":"Apple"}
+{"item":{"name":"Meta Platforms, Inc."},"output":"Meta"}
+```
+
+**Progress** (stderr):
+```
+[1/3]
+[2/3]
+[3/3]
+```
+
+### Flags
+
+| Short | Long | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `-p` | `--prompt` | yes | — | Instructions for the agent |
+| `-c` | `--concurrency` | no | `10` | Max parallel agents |
+| `-m` | `--model` | no | — | Model name |
+| `-k` | `--api-key` | no | — | Anthropic API key |
+
+## SDK
+
+```js
+import { Task } from 'atq';
+
+const task = new Task({
+  prompt: 'Normalize this company name. Return just the name.',
+  concurrency: 10,
+  model: 'claude-sonnet-4-6',
+  items: [{ name: 'Google LLC' }, { name: 'APPLE INC.' }],
+});
+
+for await (const { item, output, progress } of task.run()) {
+  console.log(`[${progress.completed}/${progress.total}] ${item.name} → ${output}`);
+}
+```
+
+### `new Task(options)`
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `prompt` | `string` | — | Instructions for the agent |
+| `concurrency` | `number` | `10` | Max parallel agents |
+| `items` | `array` | `[]` | Items to pre-load into the queue |
+| `model` | `string` | — | Model name |
+| `apiKey` | `string` | — | Anthropic API key |
+
+### `.add(item)`
+
+Add an item to the queue.
+
+### `.run()`
+
+Async generator. Each yield: `{ item, output, progress: { completed, total } }`
+
+## Install
+
+```
+npm install atq
+```

package/cli.js

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+
+import { readFileSync } from 'node:fs';
+import { parseArgs } from 'node:util';
+import { Task } from './index.js';
+
+const { values } = parseArgs({
+  options: {
+    prompt: { type: 'string', short: 'p' },
+    concurrency: { type: 'string', short: 'c' },
+    model: { type: 'string', short: 'm' },
+    'api-key': { type: 'string', short: 'k' },
+  },
+});
+
+if (!values.prompt) {
+  console.error('Usage: cat items.jsonl | atq -p "..." [-c 10] [-m model] [-k api-key]');
+  process.exit(1);
+}
+
+const lines = readFileSync('/dev/stdin', 'utf8').trim().split('\n');
+const items = lines.map(line => JSON.parse(line));
+
+const task = new Task({
+  prompt: values.prompt,
+  concurrency: values.concurrency ? parseInt(values.concurrency) : 10,
+  model: values.model,
+  apiKey: values['api-key'],
+  items,
+});
+
+for await (const { item, output, progress } of task.run()) {
+  process.stderr.write(`[${progress.completed}/${progress.total}]\n`);
+  console.log(JSON.stringify({ item, output }));
+}

package/index.js

@@ -0,0 +1,69 @@
+import { query } from '@anthropic-ai/claude-agent-sdk';
+
+export class Task {
+  constructor({ prompt, concurrency = 10, items = [], model, apiKey }) {
+    this.prompt = prompt;
+    this.concurrency = concurrency;
+    this.model = model;
+    this.apiKey = apiKey;
+    this.items = [...items];
+  }
+
+  add(item) {
+    this.items.push(item);
+  }
+
+  async *run() {
+    const total = this.items.length;
+    if (total === 0) return;
+
+    const prompt = this.prompt || '';
+
+    let completed = 0;
+    let next = 0;
+    let running = 0;
+
+    const buffer = [];
+    let waiting = null;
+
+    const push = (result) => {
+      if (waiting) { const r = waiting; waiting = null; r(result); }
+      else buffer.push(result);
+    };
+
+    const pull = () => {
+      if (buffer.length > 0) return Promise.resolve(buffer.shift());
+      return new Promise(r => { waiting = r; });
+    };
+
+    const exec = async (item) => {
+      let result = '';
+      const opts = { systemPrompt: prompt };
+      if (this.model) opts.model = this.model;
+      if (this.apiKey) opts.apiKey = this.apiKey;
+      for await (const msg of query(JSON.stringify(item), opts)) {
+        if (msg.type === 'text') result += msg.content;
+      }
+      return result.trim();
+    };
+
+    const fill = () => {
+      while (next < total && running < this.concurrency) {
+        const item = this.items[next++];
+        running++;
+        exec(item).then(raw => {
+          running--;
+          completed++;
+          push({ item, output: raw, progress: { completed, total } });
+          fill();
+        });
+      }
+    };
+
+    fill();
+
+    while (completed < total || buffer.length > 0) {
+      yield await pull();
+    }
+  }
+}

package/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@endyai/atq",
+  "version": "0.0.1",
+  "description": "A task queue for agentic workloads",
+  "type": "module",
+  "main": "index.js",
+  "exports": "./index.js",
+  "bin": {
+    "atq": "./cli.js"
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.2.81"
+  }
+}