prefactor_core.client module

prefactor_core.client module

Main client for prefactor-core.

This module provides the PrefactorCoreClient, which is the main entry point for the SDK. It manages the complete lifecycle of agent instances and spans through an async queue-based architecture.

class prefactor_core.client.PrefactorCoreClient(config: PrefactorCoreConfig, queue: Queue[Operation] | None = None, sdk_header_entry: str | None = None)

Bases: object

Main entry point for the prefactor-core SDK.

This client provides a high-level interface for managing agent instances and spans. All operations are queued and processed asynchronously, ensuring minimal impact on agent execution flow.

The client must be initialized before use, either by calling initialize() or using it as an async context manager.

Example

config = PrefactorCoreConfig(http_config=…)

async with PrefactorCoreClient(config) as client: : instance = await client.create_agent_instance(…) await instance.start()
async with instance.span(“agent:llm”) as span: : span.set_payload({“model”: “gpt-4”}) # Your agent logic here
await instance.finish()

async close() → None

Close the client and cleanup resources.

This method gracefully shuts down the executor and closes the HTTP client. It should be called when the client is no longer needed.

async create_agent_instance(agent_id: str, agent_version: dict[str, Any], agent_schema_version: dict[str, Any] | None = None, instance_id: str | None = None, external_schema_version_id: str | None = None) → AgentInstanceHandle

Create a new agent instance.

Returns immediately with a handle. The actual registration happens asynchronously via the queue.

If agent_schema_version is not provided but the client has a schema_registry, the registry’s schemas will be used automatically.

• Parameters:
  • agent_id – ID of the agent to create an instance for.
  • agent_version – Version information (name, etc.).
  • agent_schema_version – Schema version. Uses registry if not provided and registry is configured.
  • instance_id – Optional custom ID for the instance.
  • external_schema_version_id – Optional external identifier for the schema version. Defaults to “auto-generated” when using registry.
• Returns: AgentInstanceHandle for the created instance.
• Raises:
  • ClientNotInitializedError – If the client is not initialized.
  • ValueError – If no schema version provided and registry not configured.

async create_span(instance_id: str, schema_name: str, parent_span_id: str | None = None, payload: dict[str, Any] | None = None) → str

Create a span and return its ID without finishing it.

Use this for spans that need to stay open across multiple operations. Call finish_span() when done.

• Parameters:
  • instance_id – ID of the agent instance this span belongs to.
  • schema_name – Name of the schema for this span.
  • parent_span_id – Optional explicit parent span ID.
  • payload – Optional initial payload (params/inputs) stored on creation.
• Returns: The span ID.

async finish_span(span_id: str, result_payload: dict[str, Any] | None = None) → None

Finish a previously created span.

• Parameters:
  • span_id – The ID of the span to finish.
  • result_payload – Optional result data to store on the span.

async initialize() → None

Initialize the client and start processing.

This method:

1. Initializes the HTTP client
2. Starts the task executor
3. Initializes managers

• Raises: ClientAlreadyInitializedError – If already initialized.

property instance_manager : AgentInstanceManager | None

Public accessor for the agent instance manager.

span(instance_id: str, schema_name: str, parent_span_id: str | None = None, payload: dict[str, Any] | None = None)

Context manager for creating and finishing a span.

If parent_span_id is not provided, the current span from the SpanContextStack is used as the parent.

The returned SpanContext supports an explicit lifecycle:

1. await span.start(payload) — POST the span to the API.
2. Do work.
3. await span.complete(result) / span.fail(result) / span.cancel() — finish with a specific status.

If start() or a finish method is not called explicitly, the context manager handles them automatically on exit.

• Parameters:
  • instance_id – ID of the agent instance this span belongs to.
  • schema_name – Name of the schema for this span.
  • parent_span_id – Optional explicit parent span ID.
  • payload – Optional initial payload sent via auto-start on exit if start() is never called explicitly.
• Yields: SpanContext for the created span.