Python SDK

pip install "overmind[tracing]"   # the tracing SDK, every provider instrumentor, LangChain coverage
pip install overmind              # the `overmind` CLI and the inference client only

import overmind

overmind.init(
    service_name="my-service",
    environment="production",
    providers="auto",
    capability_id="support-triage",  # the capability's UUID, or its slug from overmind.toml
)

with overmind.run("triage-run", intent=request["question"], conversation_id=ticket_id) as run:
    answer = agent.invoke(request)
    run.deliver(answer)  # the terminal deliverable

class Agent:
    @overmind.run(
        intent=lambda self, *a, **k: self.task,
        conversation_id=lambda self, *a, **k: self.task_id,
    )
    async def run(self): ...

overmind.deliver(payload, *, grounded_by=None, name="deliver", provenance="agent")

from overmind import SpanType

import overmind

@overmind.tool(ignore=("session",))  # tool evidence; `session` is never captured
def search(query: str, session) -> list[dict]: ...

@overmind.observe(type="llm", capture="messages")  # full chat evidence
def call_model(messages: list[dict]) -> dict: ...

@overmind.workflow()
def research(topic: str) -> str:
    return summarise(search(topic, session))

class Tools:
    @overmind.tool(name=lambda self, action, **params: action.name)
    def act(self, action, **params): ...

with overmind.task("investment-debate", unit="turn"):
    ...  # spans here nest under the debate's turn unit

with overmind.capability("dom-element-locator", id="..."):
    locate(prompt)

start_span(name, span_type=SpanType.FUNCTION, attributes=None, *, provenance=None, unit=None)

from overmind import start_span, set_tag, SpanType

for i, doc in enumerate(documents):
    with start_span("process_document", span_type=SpanType.FUNCTION, attributes={"doc.index": i}):
        result = process(doc)
        set_tag("doc.tokens", result.tokens)

from overmind.integrations import langgraph as overmind_langgraph

overmind_langgraph.bind(
    workflow,
    # Default key per node: the slugified node name. Override where the scan
    # groups nodes differently; None opts a node out.
    behaviours={"Bull Researcher": "investment-debate", "Bear Researcher": "investment-debate"},
    deliver="Portfolio Manager",  # this node's return value is the deliverable
)
app = workflow.compile()

with overmind.run("triage", intent=question) as run:
    overmind.expect("schema", {"required_keys": ["category", "summary"]}, id="triage-shape", gate=True)
    overmind.expect("constraint", "Never promise a refund amount.", id="no-refund-promise")
    result = triage(question)
    overmind.checkpoint("classified")
    run.deliver(result)

from fastapi import FastAPI, Request
from overmind import set_user

app = FastAPI()

@app.middleware("http")
async def add_user_context(request: Request, call_next):
    user = getattr(request.state, "user", None)
    if user:
        set_user(user_id=user.id, email=user.email)
    return await call_next(request)

from overmind import PromptString

system_prompt = PromptString(
    id="support_greeter_v1",
    template="You are a helpful support agent. Your name is {agent_name}.",
    kwargs={"agent_name": "Astra"},
)

import overmind
from openai import OpenAI

overmind.init(
    service_name="customer-support",
    environment="production",
    providers="auto",
    capability_id="support-triage",
)

client = OpenAI()

@overmind.tool()
def lookup_order(order_id: str) -> dict:
    return {"id": order_id, "status": "shipped"}

@overmind.run(
    intent=lambda user_id, question: question,
    conversation_id=lambda user_id, question: user_id,
)
def handle_support_query(user_id: str, question: str) -> str:
    overmind.set_user(user_id=user_id)
    order = lookup_order("A-1001")
    response = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[
            {"role": "system", "content": "You are a helpful customer support agent."},
            {"role": "user", "content": f"{question}\n\nOrder: {order}"},
        ],
    )
    answer = response.choices[0].message.content
    overmind.deliver(answer)
    return answer