notiformer 1.0.0

Official Python SDK for Notiformer — human-in-the-loop approval gates and push notifications for AI agents.

notiformer (Python)

Official Python SDK for Notiformer — approval gates, multi-option decisions, real-time push notifications, and feature gates for AI agents. Mirrors the Node.js SDK 1:1: same methods, same config, same REST API underneath.

Install

pip install notiformer

Requires Python 3.8+.

Get started

1. Create a free account at app.notiformer.com — no credit card required for the Dev plan. Verify your email before creating a project or using the API.

2. Create a project and copy your API key (ntf_live_...).

3. Quick start:

from notiformer import Notiformer

n = Notiformer("ntf_live_...")

# 🛑 Pause and wait for Approve / Deny — always set fallback or handle the raise
try:
    result = n.ask(
        "Deploy v2 to production?",
        context="Build #442 · 3 services affected",
        timeout=300,
        fallback="deny",  # omit and a timeout raises NotiformerError
    )
    if result["approved"]:
        deploy()
    else:
        print("Timed out — auto-denied" if result["timed_out"] else "Denied")
except NotiformerError as err:
    if err.code == "timeout":
        print("No response. Respond via the app, Telegram, or Slack.")

# 🔔 Fire-and-forget alert
n.event("agents", "task_complete")

Use n = Notiformer("ntf_live_test") to try the SDK without a real key — calls are skipped locally and safe defaults are returned (a one-time setup notice is printed).

Config

Notiformer(
    api_key,
    *,
    silent=False,          # skip all calls locally, return safe defaults — good for local/dev/test
    throw_on_error=True,   # False: event()/gate() failures return a default instead of raising
    on_error=None,         # callback: fn(NotiformerError) -> None, called on every failure
)

ask()/select() always raise NotiformerError(code="timeout") when nobody responds and no fallback was set — this is unconditional and ignores throw_on_error=False. Set a fallback, or wrap the call in try/except and handle it explicitly.

API

n.event(channel, event, *, description=None, icon=None, tags=None, value=None, notify=True, recipients=None)

Fire-and-forget. Returns {"id", "createdAt", "rateLimited"?, "usageMicroUsd"?}, or None if the placeholder key or silent is used, or the call failed and throw_on_error=False.

n.ask(message, *, timeout=300, fallback=None, context=None, details=None)

Approval gate. Posts the request, then polls every 2s until it resolves. Returns {"approved", "timed_out", "responded_at"}.

n.select(message, options, *, timeout=300, fallback=None, context=None, details=None)

Like ask(), but the user picks one of 2–6 custom options instead of Approve/Deny. Each option: {"value", "label", "isDestructive"?} — use the select_option() helper:

from notiformer import select_option
select_option("stop", "🛑 Stop the pipeline", is_destructive=True)

Returns {"selected", "timed_out", "responded_at"}.

n.gate(key, *, fallback=False, cache_ttl=0)

Boolean feature-gate check. Never raises — always falls back on any error. cache_ttl (seconds) enables a local in-memory cache on this client instance only; there's no server-side caching.

n.gate_details(key, *, fallback=False, cache_ttl=0)

Same as gate(), returns {"key", "enabled", "cached"}.

n.clear_gate_cache(key=None)

Clears the local gate cache for one key, or all of them if omitted.

Errors

API and timeout failures raise notiformer.NotiformerError:

from notiformer import NotiformerError

try:
    n.ask("Deploy?", timeout=60)  # no fallback → raises on timeout
except NotiformerError as e:
    print(e.code)  # "timeout", "invalid_api_key", "rate_limited", "cap_reached", ...
    raise

.code is one of: invalid_api_key, card_required, card_locked, cap_reached, feature_not_available, validation, rate_limited, network, internal, timeout. On cap_reached, .cycle_resets_at, .manage_url, and .upgrade_url may also be set.

Request-shape mistakes (missing message, wrong number of options, a fallback that doesn't match any option, etc.) raise a plain ValueError instead — these are always raised, regardless of throw_on_error.

Links

• Documentation
• Dashboard
• Node.js SDK
• Support: [e-mail]

License

MIT