betool betool

Documentation

Deterministic Operators

Action nodes that bypass the LLM — HTTP, DB, transformations, computations.

Operators

An operator is a node that executes a deterministic action: no LLM, no randomness. For any given input, the output is predictable.

Why use them

Any logic that can be written explicitly should be. An LLM that "computes a total" or "formats a date" is an anti-pattern: it is slower, more expensive, and can make mistakes.

Practical rule: if you can write the function in 5 lines of Python, it is an operator — not an agent.

Available types

operator HTTP

Makes an HTTP call (REST, GraphQL). Configuration:

  • URL (with placeholders from context)
  • Method, headers, body
  • Authentication: bearer, basic, api_key_header (custom header), or oauth2 (see below)
  • Response mapping to slots

operator DB

Executes a query against a database registered in Administration → Databases. Supports Postgres, MySQL, MongoDB, and the internal betool database for user-defined tables.

file_transform

Transforms a file. Built-in transformers:

  • Reading (PDF with OCR, DOCX, XLSX, CSV)
  • Chunking (by page, by token chunk)
  • Conversion (HTML → text, Markdown ↔ HTML)
  • Structure extraction (JSON from a schema)

compute

Computations and aggregations over context slots:

  • Filter / map / reduce on lists
  • Column-by-column statistics (count, total, pct)
  • Schema projections
  • Compound logical conditions

payload_mapper

Composes an output payload from context slots. Useful for preparing the body of a downstream HTTP operator.

code_step

When deterministic logic exceeds what compute can handle, a code step executes custom code in a sandbox — locked by human review. See Governed Code Steps.

Authentication & secrets

Operators that communicate with an external system (HTTP, DB) reference an account registered within the organisation. Credentials are never visible inside the pipeline itself — only an account name is referenced.

As a result, rotating a password requires no edits to any pipeline.

Outbound OAuth2 (client_credentials)

For APIs that require an OAuth2 token (enterprise cloud, ERP, third-party providers), the HTTP operator supports oauth2 mode. You register an OAuth2 credential in the organisation — token_url, client_id, client_secret, scope — and the node references only a non-sensitive identifier.

At call time, betool obtains a token and reuses it as long as it remains valid; it lazily refreshes it on expiry, with no background task. The client_secret is never returned by the administration API (only a has_secret indicator is exposed), and the obtained token is placed as Authorization: Bearer … on the outbound request.

Rotating the secret after a provider-side rotation requires no pipeline edits: the next call refreshes automatically.

Idempotency

Any operator that produces a side effect (HTTP POST, DB INSERT, email send) must be designed for idempotency on the target side. Recommended practice:

  • Include an idempotency_key in the payload (typically exchange_id).
  • Check on the target side whether the key has already been processed.

betool does not automatically retry a failed operator: it is your pipeline's responsibility to orchestrate the retry strategy (loop + condition).