atalaia-emitter

Report your AI agent's runs to a Dypsis Atalaia deployment. One function, one HTTP POST, fire-and-forget: emit() returns immediately and never raises, never throws, never blocks your agent — even when Atalaia is unreachable. Zero dependencies in both languages.

Two ways in, same bytes either way:

• Install the package — pip install atalaia-emitter or npm install atalaia-emitter.
• Vendor the single file — copy atalaia_emitter.py or atalaia_emitter.ts into your agent's repo. The files are written for this: Python needs only the standard library, TypeScript needs only fetch (Node 18+, Deno, Bun, browsers).

Configuration

| Variable | Meaning | |---|---| | ATALAIA_URL | Base URL of the Atalaia API, e.g. http://atalaia:8000 | | ATALAIA_EVENT_KEY | The event API key issued by your Atalaia admin (Sources → Observed) |

Both can also be passed as arguments.

Usage

Python:

from atalaia_emitter import emit

emit("run-2026-08-15-001", process_id=PROCESS_ID, event_type="started")
emit("run-2026-08-15-001", process_id=PROCESS_ID,
     event_type="step_completed", step_name="fetch_invoices",
     metadata={"invoices_fetched": 18})
emit("run-2026-08-15-001", process_id=PROCESS_ID, event_type="completed")

TypeScript / JavaScript:

import { emit } from "atalaia-emitter";

emit("run-2026-08-15-001", { processId: PROCESS_ID, eventType: "started" });
emit("run-2026-08-15-001", {
  processId: PROCESS_ID,
  eventType: "step_completed",
  stepName: "fetch_invoices",
  metadata: { invoicesFetched: 18 },
});
emit("run-2026-08-15-001", { processId: PROCESS_ID, eventType: "completed" });

If you want budgets to work, report usage — every provider SDK returns it:

emit(run_id, process_id=PROCESS_ID, event_type="step_completed",
     step_name="classify_invoice",
     tokens_in=response.usage.input_tokens,
     tokens_out=response.usage.output_tokens,
     model="claude-haiku-4-5")

Omitting usage is honest: Atalaia reports that spend as unmeasured, never as zero.

Conventions

• event_type: started | step_completed | waiting_human | completed | failed
• step_name must match the technical step name registered in Atalaia.
• metadata must not contain personal data. Keep it to counts, ids, and plain-language error strings — plain_error_en / plain_error_pt keys are rendered to business users.
• Report the model that actually served the call, not the one you asked for, when your provider falls back.

The contract is frozen

The emitter's import list and wire format are pinned surfaces of the Atalaia product (api/tests/test_emitter_parity.py keeps the two languages identical). New versions of this package will add nothing your agent must adopt: an old vendored copy keeps working against a new Atalaia.

License

Proprietary — distributed by Dypsis AI for use with licensed Atalaia deployments. Copying either emitter file into your own agents, and running it against your Atalaia deployment, is exactly the intended use.