OTEL Guard

The Mima runtime guard detects unattested AI calls and reports them via OpenTelemetry, a local daemon socket, or a JSONL report file.

It answers the question: “Are there AI calls in my codebase that are not wrapped with @mima.attest()?”

Install

$
pip install "mima-governance[otel]"

The otel extra adds opentelemetry-api and opentelemetry-sdk.

Enable at startup

Call enable_guard() once at your application entry point, before any AI clients are instantiated.

1
from mima_governance.guard import enable_guard
2
3
enable_guard(mode="warn")   # "warn" | "block" | "report"

Modes

What the guard detects

The guard patches the __init__ method of the following AI client classes:

When one of these is called outside a function decorated with @mima.attest(), the guard fires.

How it works with @mima.attest()

The @mima.attest() decorator sets an “attested” flag before the decorated function runs and clears it afterwards. The guard checks this flag on every patched AI client call.

1
enable_guard(mode="block")
2
3
mima = MimaGovernance(api_key="...", system_name="my-system")
4
5
# This is fine — the guard sees the attested flag:
6
@mima.attest(tool_name="classify")
7
def classify(text):
8
    return openai_client.chat.completions.create(...)  # OK
9
10
# This raises MimaAttestationError in block mode:
11
def unguarded():
12
    return openai_client.chat.completions.create(...)  # BLOCKED

Thread safety: the attested flag uses threading.local, so each thread has its own value. Concurrent threads do not interfere with each other.

Async safety: async calls use a contextvars.ContextVar. Each asyncio task inherits a copy of the context, so concurrent tasks are isolated.

OpenTelemetry integration

When a real TracerProvider is configured (not the default no-op), the guard emits mima.ai_call spans for every unattested call.

1
from opentelemetry import trace
2
from opentelemetry.sdk.trace import TracerProvider
3
from opentelemetry.sdk.trace.export import BatchSpanProcessor
4
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
5
6
# Configure your OTEL SDK:
7
provider = TracerProvider()
8
provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))
9
trace.set_tracer_provider(provider)
10
11
# Now enable the guard:
12
from mima_governance.guard import enable_guard
13
enable_guard(mode="warn")

Span attributes

Report mode — ~/.mima/guard_log.jsonl

In "report" mode, every unattested call is written to ~/.mima/guard_log.jsonl as a JSONL record:

1
{"ts": "2026-06-28T09:14:22Z", "call_site": "anthropic.Anthropic.messages", "attested": false}

The file rotates at 10 MB (3 backups kept).

Review the log directly:

$
cat ~/.mima/guard_log.jsonl
$
tail -f ~/.mima/guard_log.jsonl   # live tail

Use in CI — catch gaps before production

Add enable_guard(mode="block") to your test configuration. This causes the test suite to fail fast whenever an AI call is made outside @mima.attest(), preventing unattested calls from reaching production.

1
# conftest.py
2
from mima_governance.guard import enable_guard
3
enable_guard(mode="block")

Then run your tests normally. Any unattested AI call raises MimaAttestationError and the test fails with a clear message.

Detection fallback chain

1. If a real TracerProvider is configured → emit mima.ai_call OTEL span.
2. Else if the Mima daemon socket is available → send to local daemon.
3. Else → in-process queue + background thread → JSONL report.

The fallback chain ensures the guard always works, even without an OTEL collector or Mima daemon running.

Supported AI libraries

The guard currently patches these libraries when they are installed:

• openai >= 1.0
• anthropic >= 0.20
• litellm >= 1.0

For other libraries, use mima.wrap() / @mima.attest() directly and the guard does not need to detect those calls (they are already attested).

Disabling the guard

1
from mima_governance.guard import disable_guard
2
disable_guard()

Or use per-call:

1
from mima_governance.guard import _set_attested
2
_set_attested(True)
3
response = openai_client.chat.completions.create(...)  # won't trigger guard
4
_set_attested(False)

Prefer @mima.attest() over manual flag manipulation.