Providers API Reference¶

Provider clients for interacting with observability backends.

Base Provider¶

Base provider interface for Shepherd MCP.

This module defines the abstract base classes and common exceptions for all provider implementations.

exception shepherd_mcp.providers.base.AuthenticationError[source]¶

Bases: ProviderError

Authentication failed.

class shepherd_mcp.providers.base.BaseProvider[source]¶

Bases: ABC

Abstract base class for observability providers.

All provider implementations should inherit from this class and implement the required methods.

abstractmethod close()[source]¶

Close the provider client and release resources.

Return type:: None

abstract property name: str¶: Return the provider name (e.g., ‘aiobs’, ‘langfuse’).

exception shepherd_mcp.providers.base.NotFoundError[source]¶

Bases: ProviderError

Resource not found.

exception shepherd_mcp.providers.base.ProviderError[source]¶

Bases: Exception

Base exception for provider errors.

exception shepherd_mcp.providers.base.RateLimitError[source]¶

Bases: ProviderError

Rate limit exceeded.

shepherd_mcp.providers.base.load_dotenv()[source]¶

Load environment variables from .env file.

Searches current directory and parent directories for a .env file. Only sets variables that aren’t already in the environment.

Return type:: None

AIOBS Client¶

Client for the Shepherd/AIOBS observability backend.

AIOBS provider client for Shepherd MCP.

class shepherd_mcp.providers.aiobs.AIOBSClient(api_key=None, endpoint=None)[source]¶

Bases: BaseProvider

Client for AIOBS API.

Parameters:

api_key (str | None)
endpoint (str | None)

close()[source]¶

Close the HTTP client.

Return type:: None

get_session(session_id)[source]¶

Get a specific session with its trace tree.

Parameters:: session_id (str) – The session ID to fetch.
Returns:: SessionsResponse with the session data.
Return type:: SessionsResponse

list_sessions()[source]¶

List all sessions.

Returns:: SessionsResponse with all sessions and their events.
Return type:: SessionsResponse

property name: str¶: Return the provider name.

shepherd_mcp.providers.aiobs.eval_is_failed(evaluation)[source]¶

Check if an evaluation result indicates failure.

Parameters:: evaluation (dict)
Return type:: bool

shepherd_mcp.providers.aiobs.filter_sessions(response, query=None, labels=None, provider=None, model=None, function=None, after=None, before=None, has_errors=False, evals_failed=False)[source]¶

Filter sessions based on criteria.

Parameters:

response (SessionsResponse)
query (str | None)
labels (dict[str, str] | None)
provider (str | None)
model (str | None)
function (str | None)
after (float | None)
before (float | None)
has_errors (bool)
evals_failed (bool)

Return type:

SessionsResponse

shepherd_mcp.providers.aiobs.parse_date(date_str)[source]¶

Parse a date string to Unix timestamp.

Parameters:: date_str (str)
Return type:: float

shepherd_mcp.providers.aiobs.session_has_errors(session, events, function_events)[source]¶

Check if a session has any errors.

Parameters:

session (Session)
events (list[Event])
function_events (list[FunctionEvent])

Return type:

bool

shepherd_mcp.providers.aiobs.session_has_failed_evals(session, events, function_events)[source]¶

Check if a session has any failed evaluations.

Parameters:

session (Session)
events (list[Event])
function_events (list[FunctionEvent])

Return type:

bool

shepherd_mcp.providers.aiobs.session_has_function(session, function_events, function_name)[source]¶

Check if a session has calls to the specified function.

Parameters:

session (Session)
function_events (list[FunctionEvent])
function_name (str)

Return type:

bool

shepherd_mcp.providers.aiobs.session_has_model(session, events, model)[source]¶

Check if a session has events using the specified model.

Parameters:

session (Session)
events (list[Event])
model (str)

Return type:

bool

shepherd_mcp.providers.aiobs.session_has_provider(session, events, function_events, provider)[source]¶

Check if a session has events from the specified provider.

Parameters:

session (Session)
events (list[Event])
function_events (list[FunctionEvent])
provider (str)

Return type:

bool

shepherd_mcp.providers.aiobs.session_matches_labels(session, labels)[source]¶

Check if a session has all the specified labels.

Parameters:

session (Session)
labels (dict[str, str])

Return type:

bool

shepherd_mcp.providers.aiobs.session_matches_query(session, query)[source]¶

Check if a session matches the text query.

Parameters:

session (Session)
query (str)

Return type:

bool

Langfuse Client¶

Client for the Langfuse observability platform.

Langfuse provider client for Shepherd MCP.

class shepherd_mcp.providers.langfuse.LangfuseClient(public_key=None, secret_key=None, host=None)[source]¶

Bases: BaseProvider

Client for Langfuse API.

Uses Basic Auth with public_key:secret_key. API Reference: https://api.reference.langfuse.com/

Parameters:

public_key (str | None)
secret_key (str | None)
host (str | None)

DEFAULT_HOST = 'https://cloud.langfuse.com'¶

close()[source]¶

Close the HTTP client.

Return type:: None

get_observation(observation_id)[source]¶

Get a specific observation.

Parameters:: observation_id (str) – The observation ID to fetch.
Returns:: LangfuseObservation with observation data.
Return type:: LangfuseObservation

get_score(score_id)[source]¶

Get a specific score.

Parameters:: score_id (str) – The score ID to fetch.
Returns:: LangfuseScore with score data.
Return type:: LangfuseScore

get_session(session_id)[source]¶

Get a specific session.

Parameters:: session_id (str) – The session ID to fetch.
Returns:: LangfuseSession with session data.
Return type:: LangfuseSession

get_trace(trace_id)[source]¶

Get a specific trace with its observations.

Parameters:: trace_id (str) – The trace ID to fetch.
Returns:: LangfuseTrace with full trace data including observations.
Return type:: LangfuseTrace

list_observations(limit=50, page=1, name=None, user_id=None, trace_id=None, obs_type=None, from_timestamp=None, to_timestamp=None)[source]¶

List observations with pagination and filters.

Parameters:

limit (int) – Maximum number of results per page.
page (int) – Page number (1-indexed).
name (str | None) – Filter by observation name.
user_id (str | None) – Filter by user ID.
trace_id (str | None) – Filter by trace ID.
obs_type (str | None) – Filter by type (GENERATION, SPAN, EVENT).
from_timestamp (str | None) – Filter by start timestamp.
to_timestamp (str | None) – Filter by end timestamp.

Returns:

LangfuseObservationsResponse with observations data.

Return type:

LangfuseObservationsResponse

list_scores(limit=50, page=1, name=None, user_id=None, trace_id=None, from_timestamp=None, to_timestamp=None)[source]¶

List scores with pagination and filters.

Parameters:

limit (int) – Maximum number of results per page.
page (int) – Page number (1-indexed).
name (str | None) – Filter by score name.
user_id (str | None) – Filter by user ID.
trace_id (str | None) – Filter by trace ID.
from_timestamp (str | None) – Filter by start timestamp.
to_timestamp (str | None) – Filter by end timestamp.

Returns:

LangfuseScoresResponse with scores data.

Return type:

LangfuseScoresResponse

list_sessions(limit=50, page=1, from_timestamp=None, to_timestamp=None)[source]¶

List sessions with pagination.

Parameters:

limit (int) – Maximum number of results per page.
page (int) – Page number (1-indexed).
from_timestamp (str | None) – Filter by start timestamp.
to_timestamp (str | None) – Filter by end timestamp.

Returns:

LangfuseSessionsResponse with sessions data and pagination meta.

Return type:

LangfuseSessionsResponse

list_traces(limit=50, page=1, user_id=None, name=None, session_id=None, tags=None, from_timestamp=None, to_timestamp=None)[source]¶

List traces with pagination and filters.

Parameters:

limit (int) – Maximum number of results per page.
page (int) – Page number (1-indexed).
user_id (str | None) – Filter by user ID.
name (str | None) – Filter by trace name.
session_id (str | None) – Filter by session ID.
tags (list[str] | None) – Filter by tags.
from_timestamp (str | None) – Filter by start timestamp.
to_timestamp (str | None) – Filter by end timestamp.

Returns:

LangfuseTracesResponse with traces data and pagination meta.

Return type:

LangfuseTracesResponse

property name: str¶: Return the provider name.