sigmoda 0.1.0

Sigmoda Python SDK for logging LLM events and OpenAI chat completions.

Sigmoda Python SDK

Sigmoda is an LLM observability and guardrails platform. This SDK gives you:

• A thin wrapper around OpenAI chat completions that measures latency, captures prompt/response/token usage, logs to Sigmoda, and returns the original OpenAI response.
• A log_event helper to send custom LLM events (for other providers or bespoke flows).

Install

pip install sigmoda

Configure

Set keys via environment variables (recommended):

export SIGMODA_PROJECT_KEY="YOUR_SIGMODA_PROJECT_KEY"
export OPENAI_API_KEY="YOUR_OPENAI_API_KEY"

# Optional (only if your Sigmoda setup requires it)
export SIGMODA_PROJECT_ID="YOUR_SIGMODA_PROJECT_ID"

# Optional
export SIGMODA_ENV="prod"          # prod|stage|dev
export SIGMODA_API_URL="https://api.sigmoda.com"
export SIGMODA_DISABLED="0"        # set to 1 to disable logging
export SIGMODA_DEBUG="0"           # set to 1 for debug logs
export SIGMODA_SAMPLE_RATE="1.0"   # 0.0 - 1.0
export SIGMODA_MAX_PAYLOAD_BYTES="100000"

import sigmoda

sigmoda.init(
    # Reads env vars by default:
    # - SIGMODA_PROJECT_KEY (required unless SIGMODA_DISABLED=1)
    # - SIGMODA_PROJECT_ID (optional)
    # - SIGMODA_ENV / SIGMODA_API_URL / SIGMODA_DISABLED / SIGMODA_DEBUG (optional)

    # Privacy controls (optional)
    # capture_content=False,            # don't send prompt/response text
    # redact=lambda s: "[REDACTED]",    # redact prompt/response + string metadata values
)

Wrap OpenAI chat completions

resp = sigmoda.openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Draft a friendly greeting."}],
    sigmoda_metadata={"route": "welcome-flow", "user_id": "123"},
)

# Use the OpenAI response as usual
print(resp.choices[0].message.content)

What happens:

• SDK times the call, reads token usage if present, and sends a best-effort log to Sigmoda (prompt/response text only if capture_content=True).
• Logging is fire-and-forget on a single background worker with a bounded queue; when full, events are dropped (never break your app).
• Network sends use short timeouts + small retries for transient errors.
• Tool call names (if any) are captured in metadata["_sigmoda"]["tool_call_names"].

You can inspect drop/retry counters and flush on shutdown:

print(sigmoda.get_stats())
sigmoda.flush(timeout=2.0)

Streaming

Streaming is supported: if you pass stream=True, the SDK returns the OpenAI stream and logs an event once the stream is fully consumed.

Notes

• Metadata is sanitized (JSON-safe) and bounded by defaults (max_metadata_items=50, max_metadata_bytes=8192).
• Set SIGMODA_DISABLED=1 (or disabled=True) to fully no-op logging.
• In SIGMODA_ENV=prod, capture_content defaults to False (no prompt/response text captured). Set capture_content=True only if you’re sure it’s safe.
• Defaults: timeout=2s, max_retries=2, max_queue_size=1000, sample_rate=1.0, max_payload_bytes=100000, max_prompt_chars=8000, max_response_chars=8000.
• Use sigmoda_metadata={...} for Sigmoda metadata; OpenAI’s own metadata=... parameter (if you pass it) is forwarded to OpenAI.

Troubleshooting

export SIGMODA_DEBUG=1

import sigmoda
print(sigmoda.get_stats())  # queue_size, dropped_queue_full, failed, retries, sent

Common issues:

• SIGMODA_DISABLED=1 set (no logs by design).
• Wrong SIGMODA_API_URL (check failed / retries counters).
• Missing SIGMODA_PROJECT_KEY (init will raise unless disabled).

Log a custom event

sigmoda.log_event(
    provider="my-llm",
    model="alpha-1",
    type="chat_completion",
    prompt="Translate 'hello' to French.",
    response="Bonjour",
    tokens_in=4,
    tokens_out=2,
    duration_ms=85,
    status="ok",
    metadata={"route": "translator"},
)

Development

• Python 3.8+.
• Runtime deps: requests, openai>=1,<2.
• Tests: pytest. Run locally with:

python3 -m venv .venv
. .venv/bin/activate
pip install -e ".[test]"
pytest

See MVP_CHECKLIST.md and DEV_NOTES.md for progress tracking.