Factories

synth_ai.research.factories

client.research.factories — Factory domain (Tag under factories.tag).

Classes

ResearchFactoriesTagSessionsMessagesAPI

Send steering messages to an active Factory Tag session.

Methods:

send

send(self, session_id: str, message: TagMessageRequest | Mapping[str, Any] | dict[str, Any] | str) -> TagSession

Post a message to a Tag session and return the updated session state.

Args:

• session_id: Tag session id from sessions.create.
• message: TagMessageRequest, mapping, or plain string body.
• metadata: Optional message metadata.
• idempotency_key: Optional idempotency key for safe retries.

Returns:

• Updated TagSession after the message is accepted.

ResearchFactoriesTagSessionsAPI

Create and inspect Factory Tag sessions.

Methods:

messages

messages(self) -> ResearchFactoriesTagSessionsMessagesAPI

Nested API for sending Tag session messages.

create

create(self, request: TagSessionCreateRequest) -> TagSession

Start a Factory Tag session for a one-off research task.

Args:

• request: Fully typed Tag session request.

Returns:

• Created TagSession with ids needed for messages.send.

get

get(self, session_id: str) -> TagSession

Fetch the current Tag session state and terminal receipt fields.

list

list(self) -> tuple[TagSession, ...]

List Tag sessions, optionally filtered by factory or effort.

Args:

• factory_id: Only sessions bound to this factory.
• effort_id: Only sessions bound to this effort.
• limit: Maximum sessions returned (newest first).

Returns:

• Tuple of TagSession records.

watch

watch(self, session_id: str) -> TagSessionWatch

Open a watch handle that polls the session until it is terminal.

Args:

• session_id: Tag session to observe.

Returns:

• TagSessionWatch iterator of session state snapshots.

control

control(self, session_id: str, action: TagSessionControlAction | str) -> TagSession

Apply a control action (for example pause, resume, cancel) to a session.

Args:

• session_id: Tag session to control.
• action: TagSessionControlAction or its string value.

Returns:

• Updated TagSession after the action is applied.

get_factory_context

get_factory_context(self, session_id: str) -> TagFactoryContext

Read the Factory champion and candidate context bound to a session.

ResearchFactoriesTagScopesAPI

Resolve default Tag scopes for an organization.

Methods:

get_default

get_default(self) -> TagScope

Return the org default Tag scope used when scope_id is omitted.

get_factory_context

get_factory_context(self, scope_id: str = 'default') -> TagFactoryContext

Read Factory champion and candidate context for a Tag scope.

ResearchFactoriesTagAPI

Factory Tag namespace — delegate short research tasks from your IDE.

Methods:

sessions

sessions(self) -> ResearchFactoriesTagSessionsAPI

Create Tag sessions and send steering messages.

scopes

scopes(self) -> ResearchFactoriesTagScopesAPI

Read Tag scope defaults for the org.

ResearchFactoryCandidatesAPI

Immutable Factory candidates and benchmark-owned grading intake.

Methods:

list

list(self, factory_id: str) -> tuple[FactoryCandidate, ...]

List candidates, optionally filtered by grading status or Effort.

record_grading

record_grading(self, factory_id: str, candidate_id: str, request: FactoryCandidateGradingRequest | Mapping[str, Any] | dict[str, Any]) -> FactoryCandidate

Record a benchmark-owned grading result for one immutable candidate.

ResearchFactoryChampionsAPI

Deterministic champion selection and append-only decision history.

Methods:

select

select(self, factory_id: str, request: FactoryChampionSelectRequest | Mapping[str, Any] | dict[str, Any]) -> FactoryChampionDecision

Select the deterministic winner when it strictly beats the baseline.

rollback

rollback(self, factory_id: str, request: FactoryChampionRollbackRequest | Mapping[str, Any] | dict[str, Any]) -> FactoryChampionDecision

Roll the champion pointer back and append the decision event.

list_events

list_events(self, factory_id: str) -> tuple[FactoryChampionEvent, ...]

List the append-only champion decision history, newest first.

ResearchFactoriesAPI

Research Factory workflow API.

The status projection is the shared workflow model for SDK, MCP, and the dashboard: experiments, outputs, decisions, limits, health, and next wake all come from the backend rather than being reconstructed by each client.

Methods:

candidates

candidates(self) -> ResearchFactoryCandidatesAPI

Immutable candidate discovery and benchmark-owned grading intake.

champions

champions(self) -> ResearchFactoryChampionsAPI

Deterministic champion selection, rollback, and decision history.

tag

tag(self) -> ResearchFactoriesTagAPI

Factory Tag — short-lived delegated research sessions.

list

list(self) -> tuple[Factory, ...]

List Research Factories visible to the authenticated organization.

get

get(self, factory_id: str) -> Factory

Fetch one Research Factory.

status

status(self, factory_id: str) -> FactoryStatus

Read the backend-owned Factory workflow projection.

open

open(self, factory_id: str) -> ResearchFactoryHandle

Open a handle bound to one Factory id (no network call).

pause

pause(self, factory_id: str) -> Factory

Pause a Factory. Backend route: PATCH /smr/factories/{factory_id}.

resume

resume(self, factory_id: str) -> Factory

Resume a Factory. Backend route: PATCH /smr/factories/{factory_id}.

archive

archive(self, factory_id: str) -> Factory

Archive a Factory. Backend route: PATCH /smr/factories/{factory_id}.

watch_status

watch_status(self, factory_id: str) -> Iterator[FactoryStatus]

Poll the status projection until idle or timeout.

Backend route: repeated GET /smr/factories/{factory_id}/status.

usage

usage(self, factory_id: str) -> FactoryUsage

Read the factory-level usage aggregate (cost, budget, per-effort drawdown).

Backend route: GET /smr/factories/{factory_id}/usage (query window: month_to_date | last_7_days).

events

events(self, factory_id: str) -> FactoryEventsPage

Read one newest-first page of durable factory events.

Backend route: GET /smr/factories/{factory_id}/events (query limit 1-500, cursor).

iter_events

iter_events(self, factory_id: str) -> Iterator[FactoryEvent]

Yield durable factory events, paging until next_cursor drains.

Backend route: repeated GET /smr/factories/{factory_id}/events. Stops when next_cursor is null or repeats (bounded; no sleeps).

preview_wake

preview_wake(self, factory_id: str) -> FactoryWakeDueResult

Preview due experiments and launch consequences without starting runs.

wake_due

wake_due(self, factory_id: str) -> FactoryWakeDueResult

Launch exactly the due experiments bound to a reviewed preview.