Models API Reference

Data models for representing sessions, traces, events, and observations.

AIOBS Models

Models for the Shepherd/AIOBS backend.

AIOBS-specific models.

These models represent the data structures for the Shepherd/AIOBS backend.

class shepherd_mcp.models.aiobs.Callsite(*, file, line, function)[source]

Bases: BaseModel

Code location where a call was made.

Parameters:
file: str
function: str
line: int
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class shepherd_mcp.models.aiobs.Evaluation(*, id=None, eval_type=None, score=None, passed=None, label=None, result=None, feedback=None, human_feedback=None, evaluator=None, latency_ms=None, status=None, error=None, created_at=None)[source]

Bases: BaseModel

Evaluation result.

Parameters:

  • id (str | None)

  • eval_type (str | None)

  • score (float | None)

  • passed (bool | None)

  • label (str | None)

  • result (dict[str, Any] | None)

  • feedback (str | None)

  • human_feedback (str | None)

  • evaluator (str | None)

  • latency_ms (float | None)

  • status (str | None)

  • error (str | None)

  • created_at (str | None)

created_at: str | None
error: str | None
eval_type: str | None
evaluator: str | None
feedback: str | None
human_feedback: str | None
id: str | None
label: str | None
latency_ms: float | None
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

passed: bool | None
result: dict[str, Any] | None
score: float | None
status: str | None
class shepherd_mcp.models.aiobs.Event(*, provider, api, request=<factory>, response=None, error=None, started_at, ended_at, duration_ms, callsite=None, span_id, parent_span_id=None, session_id, evaluations=<factory>)[source]

Bases: BaseModel

LLM provider event (e.g., OpenAI, Anthropic calls).

Parameters:
api: str
callsite: Callsite | None
duration_ms: float
ended_at: float
error: str | None
evaluations: list[dict[str, Any]]
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

parent_span_id: str | None
provider: str
request: dict[str, Any]
response: dict[str, Any] | None
session_id: str
span_id: str
started_at: float
class shepherd_mcp.models.aiobs.FunctionEvent(*, provider, api, name, module=None, args=None, kwargs=None, result=None, error=None, started_at, ended_at, duration_ms, callsite=None, span_id, parent_span_id=None, enh_prompt=False, enh_prompt_id=None, auto_enhance_after=None, session_id, evaluations=<factory>)[source]

Bases: BaseModel

Observed function event.

Parameters:
api: str
args: list[Any] | None
auto_enhance_after: int | None
callsite: Callsite | None
duration_ms: float
ended_at: float
enh_prompt: bool
enh_prompt_id: str | None
error: str | None
evaluations: list[dict[str, Any]]
kwargs: dict[str, Any] | None
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

module: str | None
name: str
parent_span_id: str | None
provider: str
result: Any
session_id: str
span_id: str
started_at: float
class shepherd_mcp.models.aiobs.Session(*, id, name, started_at, ended_at=None, meta=<factory>, labels=<factory>)[source]

Bases: BaseModel

Session metadata.

Parameters:
ended_at: float | None
id: str
labels: dict[str, str]
meta: dict[str, Any]
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str
started_at: float
class shepherd_mcp.models.aiobs.SessionsResponse(*, sessions=<factory>, events=<factory>, function_events=<factory>, trace_tree=<factory>, enh_prompt_traces=<factory>, generated_at=0, version=1)[source]

Bases: BaseModel

Response from /v1/sessions or /v1/sessions/{id}/tree.

Parameters:
enh_prompt_traces: list[Any]
events: list[Event]
function_events: list[FunctionEvent]
generated_at: float
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

sessions: list[Session]
trace_tree: list[TraceNode]
version: int
class shepherd_mcp.models.aiobs.TraceNode(*, provider, api, request=None, response=None, name=None, module=None, args=None, kwargs=None, result=None, error=None, started_at, ended_at, duration_ms, span_id, parent_span_id=None, session_id, event_type=None, children=<factory>, evaluations=<factory>)[source]

Bases: BaseModel

Node in the trace tree (can be either provider or function event).

Parameters:
api: str
args: list[Any] | None
children: list[TraceNode]
duration_ms: float
ended_at: float
error: str | None
evaluations: list[dict[str, Any]]
event_type: str | None
kwargs: dict[str, Any] | None
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

module: str | None
name: str | None
parent_span_id: str | None
provider: str
request: dict[str, Any] | None
response: dict[str, Any] | None
result: Any
session_id: str
span_id: str
started_at: float

Langfuse Models

Models for the Langfuse platform.

Langfuse-specific models.

These models represent Langfuse’s data structures for traces, observations, sessions, and scores. They are separate from AIOBS models.

class shepherd_mcp.models.langfuse.LangfuseObservation(*, id, traceId, type, name=None, startTime, endTime=None, completionStartTime=None, model=None, modelParameters=None, input=None, output=None, usage=None, level=None, statusMessage=None, parentObservationId=None, version=None, metadata=None, latency=None, timeToFirstToken=None, promptId=None, promptName=None, promptVersion=None, calculatedInputCost=None, calculatedOutputCost=None, calculatedTotalCost=None)[source]

Bases: BaseModel

Observation (generation, span, or event) in Langfuse.

Parameters:

  • id (str)

  • traceId (str)

  • type (str)

  • name (str | None)

  • startTime (str)

  • endTime (str | None)

  • completionStartTime (str | None)

  • model (str | None)

  • modelParameters (dict[str, Any] | None)

  • input (Any | None)

  • output (Any | None)

  • usage (dict[str, Any] | None)

  • level (str | None)

  • statusMessage (str | None)

  • parentObservationId (str | None)

  • version (str | None)

  • metadata (dict[str, Any] | None)

  • latency (float | None)

  • timeToFirstToken (float | None)

  • promptId (str | None)

  • promptName (str | None)

  • promptVersion (int | None)

  • calculatedInputCost (float | None)

  • calculatedOutputCost (float | None)

  • calculatedTotalCost (float | None)

calculated_input_cost: float | None
calculated_output_cost: float | None
calculated_total_cost: float | None
completion_start_time: str | None
end_time: str | None
id: str
input: Any | None
latency: float | None
level: str | None
metadata: dict[str, Any] | None
model: str | None
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_parameters: dict[str, Any] | None
name: str | None
output: Any | None
parent_observation_id: str | None
prompt_id: str | None
prompt_name: str | None
prompt_version: int | None
start_time: str
status_message: str | None
time_to_first_token: float | None
trace_id: str
type: str
usage: dict[str, Any] | None
version: str | None
class shepherd_mcp.models.langfuse.LangfuseObservationsResponse(*, data=<factory>, meta=<factory>)[source]

Bases: BaseModel

Response from /api/public/observations.

Parameters:
data: list[LangfuseObservation]
meta: dict[str, Any]
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class shepherd_mcp.models.langfuse.LangfuseScore(*, id, traceId, observationId=None, name, value=None, stringValue=None, timestamp, source, dataType, comment=None, configId=None)[source]

Bases: BaseModel

Score/evaluation in Langfuse.

Parameters:

  • id (str)

  • traceId (str)

  • observationId (str | None)

  • name (str)

  • value (float | str | None)

  • stringValue (str | None)

  • timestamp (str)

  • source (str)

  • dataType (str)

  • comment (str | None)

  • configId (str | None)

comment: str | None
config_id: str | None
data_type: str
id: str
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str
observation_id: str | None
source: str
string_value: str | None
timestamp: str
trace_id: str
value: float | str | None
class shepherd_mcp.models.langfuse.LangfuseScoresResponse(*, data=<factory>, meta=<factory>)[source]

Bases: BaseModel

Response from /api/public/scores.

Parameters:
data: list[LangfuseScore]
meta: dict[str, Any]
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class shepherd_mcp.models.langfuse.LangfuseSession(*, id, createdAt, projectId, userIds=<factory>, countTraces=0, sessionDuration=None, inputCost=0, outputCost=0, totalCost=0, inputTokens=0, outputTokens=0, totalTokens=0, totalCount=0, traces=<factory>)[source]

Bases: BaseModel

Session in Langfuse grouping related traces.

Parameters:
count_traces: int
created_at: str
id: str
input_cost: float
input_tokens: int
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

output_cost: float
output_tokens: int
project_id: str
session_duration: float | None
total_cost: float
total_count: int
total_tokens: int
traces: list[LangfuseTrace]
user_ids: list[str]
class shepherd_mcp.models.langfuse.LangfuseSessionsResponse(*, data=<factory>, meta=<factory>)[source]

Bases: BaseModel

Response from /api/public/sessions.

Parameters:
data: list[LangfuseSession]
meta: dict[str, Any]
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class shepherd_mcp.models.langfuse.LangfuseTrace(*, id, timestamp, name=None, userId=None, sessionId=None, release=None, version=None, metadata=None, tags=<factory>, public=False, input=None, output=None, latency=None, totalCost=None, observations=<factory>)[source]

Bases: BaseModel

Trace in Langfuse representing a complete workflow or conversation.

Parameters:
id: str
input: Any | None
latency: float | None
metadata: dict[str, Any] | None
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str | None
observations: list[str | LangfuseObservation]
output: Any | None
public: bool
release: str | None
session_id: str | None
tags: list[str]
timestamp: str
total_cost: float | None
user_id: str | None
version: str | None
class shepherd_mcp.models.langfuse.LangfuseTracesResponse(*, data=<factory>, meta=<factory>)[source]

Bases: BaseModel

Response from /api/public/traces.

Parameters:
data: list[LangfuseTrace]
meta: dict[str, Any]
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].