Insight Ingestion (SDK)

Send traces and scores directly to Insight from external agent pipelines using the SDK ingestion helpers.

Use this integration when you already have externally produced trace/score results (for example, evaluator outputs, CSV processing jobs, or custom agent runners) and want to write them into Insight without relying only on OTLP auto-instrumentation.

When to use this vs tracing export

Use Insight Export when you want automatic OpenTelemetry span export from instrumented app runtime.
Use this SDK ingestion helper when you need explicit event submission for traces and scores produced outside the runtime.

Install and authenticate

Install

pip install mantisdk

Configure credentials

export INSIGHT_HOST="https://insight.withmetis.ai"
export INSIGHT_PUBLIC_KEY="pk-lf-..."
export INSIGHT_SECRET_KEY="sk-lf-..."

Optional client from environment

from mantisdk import InsightIngestionClient
 
client = InsightIngestionClient.from_env()

API surface

from mantisdk import InsightIngestionClient, InsightIngestionConfig
 
client = InsightIngestionClient(
    InsightIngestionConfig(
        host="https://insight.withmetis.ai",
        public_key="pk-lf-...",
        secret_key="sk-lf-...",
        max_batch_size=200,
    )
)

`from_env()`

Create a client from INSIGHT_HOST, INSIGHT_PUBLIC_KEY, and INSIGHT_SECRET_KEY.

`ingest_trace_event(...)`

Send a single trace-create event through /api/public/ingestion.

`send_score_api(score)`

Send a single score directly to /api/public/scores.

`send_scores(scores, mode=...)`

Send many scores with two modes:

ingestion-batch (default): score-create events batched to /api/public/ingestion
scores-api: one score per request to /api/public/scores

Score target rules (strict)

Insight scores must target exactly one object type:

traceId
sessionId
datasetRunId

Do not send more than one target in the same score payload.

Production guidance

Prefer batching for throughput

client.send_scores(
    [
        {"name": "task_success", "value": 0.94, "dataType": "NUMERIC", "traceId": "trace-1"},
        {"name": "safety", "value": 1, "dataType": "BOOLEAN", "traceId": "trace-1"},
    ],
    mode="ingestion-batch",
)

Use direct API mode when per-score response semantics matter

client.send_scores(
    [{"name": "task_success", "value": 0.94, "dataType": "NUMERIC", "traceId": "trace-1"}],
    mode="scores-api",
)

Common failure modes

401/403: invalid keys or wrong project scope
400: invalid score payload (often target ID rule violation)
429: rate limits; retry with backoff
5xx: transient service error; retry safely

End-to-end example

from mantisdk import InsightIngestionClient, InsightIngestionConfig
 
client = InsightIngestionClient(
    InsightIngestionConfig(
        host="https://insight.withmetis.ai",
        public_key="pk-lf-...",
        secret_key="sk-lf-...",
    )
)
 
client.ingest_trace_event(
    trace_id="trace-sdk-001",
    name="External Agent Trace",
    input_data={"query": "help me with refunds"},
    output_data={"answer": "refund initiated"},
    session_id="session-001",
    environment="production",
)
 
client.send_scores(
    [
        {"name": "task_success", "value": 0.97, "dataType": "NUMERIC", "traceId": "trace-sdk-001"},
        {"name": "policy_compliant", "value": 1, "dataType": "BOOLEAN", "traceId": "trace-sdk-001"},
    ],
    mode="ingestion-batch",
)

Next steps

Overview Mantis MCP Server