Assistants API¶
assistants ¶
Durable long-lived assistants with an inbox and scheduler.
SPEND_EXHAUSTED
module-attribute
¶
The blocker reason of an llm assistant held back by the daily spend cap.
ArtifactMeta ¶
Lifecycle metadata of one artifact (its screen is the view view_name).
UnknownArtifact ¶
No artifact has this id.
CodeHandler ¶
An in-process handler bound to a code assistant.
StateValidationError ¶
Assistant state does not satisfy the assistant's state schema.
WakeContext ¶
WakeContext(
*,
address: str,
now: datetime,
state: dict[str, Any],
state_schema: dict[str, Any] | None,
contracts: ContractRegistry,
clock: Callable[[], datetime] | None = None,
ui_registry: ComponentRegistry | None = None,
base_context: dict[str, Any] | None = None,
stored_views: list[ViewSpec] | None = None,
artifact_status: Callable[[str], Awaitable[str | None]]
| None = None,
)
What a handler sees while processing one message.
Sends, state changes, scheduled wakes and published views are buffered here; the runtime commits them together with the message completion in one transaction, or discards them all if the handler raises.
Attributes:
| Name | Type | Description |
|---|---|---|
address |
The assistant being run. |
|
now |
The time this context was created (tz-aware). |
|
state |
Working copy of the assistant's state. |
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
address
|
str
|
The assistant being run. |
required |
now
|
datetime
|
Current time (tz-aware). |
required |
state
|
dict[str, Any]
|
Persisted state; the context works on a deep copy. |
required |
state_schema
|
dict[str, Any] | None
|
JSON Schema for the state, or |
required |
contracts
|
ContractRegistry
|
Registry used to validate outgoing messages. |
required |
clock
|
Callable[[], datetime] | None
|
Timestamp source for outgoing messages; defaults to |
None
|
ui_registry
|
ComponentRegistry | None
|
Components views may use; defaults to
:func: |
None
|
base_context
|
dict[str, Any] | None
|
Binding context views are validated against (with
|
None
|
stored_views
|
list[ViewSpec] | None
|
The assistant's views as stored before this wake. Only
the LLM |
None
|
artifact_status
|
Callable[[str], Awaitable[str | None]] | None
|
Async lookup of the status of this assistant's artifact
|
None
|
Source code in orqest/assistants/context.py
views
property
¶
Buffered views, one per name, in first-publish order (deep copies).
artifacts
property
¶
Buffered artifact changes by id: a show, or None for a dismissal (a copy).
send ¶
send(
recipient: str,
message_type: str,
payload: dict[str, Any],
*,
reply_to: str | None = None,
) -> str
Buffer a message to recipient and return its id.
The payload is JSON round-tripped, so the buffered copy is exactly what will be persisted.
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
TypeError
|
If |
ContractViolation
|
If the recipient's contracts reject the message. |
Source code in orqest/assistants/context.py
reply ¶
Buffer a reply to message's sender; return the new message id.
update_state ¶
Merge-patch the working state and validate it against the schema.
Returns:
| Type | Description |
|---|---|
dict[str, Any]
|
The new working state. |
Raises:
| Type | Description |
|---|---|
StateValidationError
|
If the patch is not a dict or the patched state is not a JSON-serialisable dict satisfying the schema; the working copy is left unchanged. |
Source code in orqest/assistants/context.py
schedule_once ¶
publish_view ¶
Validate spec and buffer it, replacing any view of the same name.
The view is JSON round-tripped first, so the buffered copy is exactly
what will be persisted and later handler mutations cannot change it.
It is validated against the base context with "state" set to the
working state. Bindings that do not resolve are not problems (they
render as placeholders); they are returned as warnings.
Returns:
| Type | Description |
|---|---|
list[str]
|
One warning per binding that does not resolve in that context |
list[str]
|
(empty when all resolve). |
Raises:
| Type | Description |
|---|---|
TypeError
|
If |
ViewValidationError
|
If the view has structural problems. |
Source code in orqest/assistants/context.py
show_artifact ¶
show_artifact(
artifact_id: str,
*,
intent: str,
title: str,
a11y_label: str,
root: ViewNode,
allowed_actions: list[str] | None = None,
expires_in_s: float | None = None,
source_refs: list[str] | None = None,
approval_requirements: list[str] | None = None,
) -> list[str]
Buffer an artifact to show: created, or updated if the id exists (version +1).
The tree is validated like :meth:publish_view and becomes the view
art-<artifact_id>. Showing an id again in one wake replaces the earlier
show (one version bump); showing a dismissed or expired artifact makes it
active again. A pinned artifact stays pinned, and a show of one the owner kept
frozen is ignored. An id with no artifact that names one of this assistant's
views fails the commit.
Returns:
| Type | Description |
|---|---|
list[str]
|
One warning per binding that does not resolve. |
Raises:
| Type | Description |
|---|---|
ValueError
|
For a malformed field or id, a bad |
TypeError
|
If the tree is not JSON-serialisable. |
Source code in orqest/assistants/context.py
dismiss_artifact ¶
Buffer the dismissal of an artifact (a no-op at commit if it isn't on screen).
Dismissing an id shown earlier in the same wake drops that show. A pinned artifact can't be dismissed by the assistant: the commit leaves it as it is.
Source code in orqest/assistants/context.py
artifact_status
async
¶
The status of this assistant's artifact artifact_id, or None (no such one).
"kept" stands for pinned and frozen: the owner kept the screen as they saw it.
Source code in orqest/assistants/context.py
has_stored_view ¶
validate ¶
Check everything buffered can be persisted (handlers may mutate directly).
Normalises state to its JSON form. Views need no check here: they
are validated and JSON round-tripped when published.
Raises:
| Type | Description |
|---|---|
StateValidationError
|
If the working state is not a JSON-serialisable dict satisfying the schema. |
TypeError
|
If a buffered message payload is not JSON-serialisable. |
Source code in orqest/assistants/context.py
Contract ¶
Declares one message type an address accepts, with its payload schema.
ContractRegistry ¶
Registry of contracts keyed by (address, message_type).
Source code in orqest/assistants/contracts.py
register ¶
Register a contract.
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
Source code in orqest/assistants/contracts.py
get ¶
Return the contract for (address, message_type) or None.
for_address ¶
validate ¶
Validate a message against the recipient's contracts.
A recipient with no contracts accepts anything.
Raises:
| Type | Description |
|---|---|
ContractViolation
|
If the type is not contracted or the payload fails schema validation. |
Source code in orqest/assistants/contracts.py
ContractViolation ¶
A message does not satisfy the recipient's contracts.
ViewSnapshot ¶
A view as a renderer should show it, with the event sequence it reflects.
Attributes:
| Name | Type | Description |
|---|---|---|
resolved |
ResolvedView
|
The resolved view. |
seq |
int
|
The |
Message ¶
A message addressed to an assistant (or runtime endpoint).
Attributes:
| Name | Type | Description |
|---|---|---|
id |
str
|
Unique message id (uuid4 by default). |
sender |
str
|
Address of the sender. |
recipient |
str
|
Address of the recipient. |
type |
str
|
Message type, matching |
payload |
dict[str, Any]
|
JSON payload. |
reply_to |
str | None
|
Id of the message this replies to, if any. |
status |
MessageStatus
|
Delivery lifecycle state. |
attempts |
int
|
Number of processing attempts so far. |
available_at |
datetime
|
Earliest time the message may be processed (tz-aware). |
created_at |
datetime
|
Creation time (tz-aware). |
last_error |
str | None
|
Error from the most recent failed attempt. |
AssistantRuntime ¶
AssistantRuntime(
db_path: str | Path,
*,
factory: AgentFactory | None = None,
contracts: ContractRegistry | None = None,
memory: MemoryStore | None = None,
bus: EventBus | None = None,
clock: Callable[[], datetime] = _utc_now,
model: Model | None = None,
max_attempts: int = 5,
backoff_base_s: float = 2.0,
run_timeout_s: float | None = 300.0,
ui_registry: ComponentRegistry | None = None,
view_context: Callable[
[AssistantRecord], Awaitable[dict[str, Any]]
]
| None = None,
view_context_timeout_s: float | None = 5.0,
default_views: tuple[str, ...] = (),
model_for: Callable[
[AssistantRecord, list[Message]], Model | None
]
| None = None,
usage_limits: UsageLimits | None = UsageLimits(
request_limit=20, tool_calls_limit=40
),
daily_token_budget: int | None = None,
budget_tz: str = "UTC",
spend_cap: SpendCap | None = None,
keeper: Keeper | None = None,
owner_senders: frozenset[str] = frozenset(),
wake_context: Callable[
[AssistantRecord, list[Message]],
Awaitable[dict[str, Any] | None],
]
| None = None,
)
Runs durable assistants over one SQLite database.
Every processed message is either fully committed (state change, outgoing messages, scheduled wakes, published views, artifact changes and the message's completion in one transaction) or leaves no trace beyond a retry/failure record. The exception is a keeper's compartment tools: they act on the keeper's own file at once, so a run that fails afterwards keeps what they did. Use as an async context manager.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
db_path
|
str | Path
|
SQLite database file (created if missing). |
required |
factory
|
AgentFactory | None
|
Agent factory that spawns llm assistants; required by
:meth: |
None
|
contracts
|
ContractRegistry | None
|
Message contracts; defaults to an empty registry (accept all). |
None
|
memory
|
MemoryStore | None
|
Optional episodic memory for llm assistants (best-effort). |
None
|
bus
|
EventBus | None
|
Event bus for runtime events such as dead-lettered messages, and
for live views, emitted best-effort after each commit (see
:class: |
None
|
clock
|
Callable[[], datetime]
|
Source of tz-aware "now". |
_utc_now
|
model
|
Model | None
|
Model for llm assistants; |
None
|
max_attempts
|
int
|
Processing attempts before a message is marked failed. A message whose attempt crashes the process counts that attempt too: at startup, an interrupted message that has used all its attempts is dead-lettered instead of being retried. |
5
|
backoff_base_s
|
float
|
Base of the exponential retry backoff, in seconds. |
2.0
|
run_timeout_s
|
float | None
|
Time limit for one handler call or model run; on
expiry the run fails with |
300.0
|
ui_registry
|
ComponentRegistry | None
|
Components assistants' views may use; defaults to
:func: |
None
|
view_context
|
Callable[[AssistantRecord], Awaitable[dict[str, Any]]] | None
|
Async builder of the binding context views are
validated against (see :class: |
None
|
view_context_timeout_s
|
float | None
|
Budget for one |
5.0
|
default_views
|
tuple[str, ...]
|
View names every llm assistant shows: each one it has
not published is a :func: |
()
|
daily_token_budget
|
int | None
|
Daily tokens for llm assistants whose spec sets
none; |
None
|
budget_tz
|
str
|
IANA zone whose midnight starts a new budget day (also the spend cap's day). |
'UTC'
|
spend_cap
|
SpendCap | None
|
A daily cap on what all assistants spend together (see
:class: |
None
|
keeper
|
Keeper | None
|
An open compartments keeper (the application opens and closes it). Each wake of an llm assistant reads its grants, which decide its compartment tools and whether its sends and memories get a leak check. If they cannot be read, the wake fails and is retried. |
None
|
owner_senders
|
frozenset[str]
|
Senders whose messages count as the owner's when a compartment release is prepared. Empty: no wake can prepare one. |
frozenset()
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
Source code in orqest/assistants/runtime.py
inbox
property
¶
The message inbox, for read-only inspection by tests and admin views.
Calls on it bypass the runtime's transaction lock, so they may observe a concurrently running tick's uncommitted writes. Do not write through it.
__aenter__
async
¶
Open the database and recover messages interrupted by a crash.
An interrupted (processing) message that has used all
max_attempts crashed the runtime on its last attempt: it is
dead-lettered (assistant.message.dead). Others return to pending.
Source code in orqest/assistants/runtime.py
__aexit__
async
¶
get
async
¶
Fetch an assistant record.
Raises:
| Type | Description |
|---|---|
UnknownRecipient
|
If no assistant has this address. |
Source code in orqest/assistants/runtime.py
register_code
async
¶
register_code(
address: str,
handler: CodeHandler,
*,
state_schema: dict[str, Any] | None = None,
initial_state: dict[str, Any] | None = None,
) -> None
Bind an in-process handler, creating the code record if missing.
An existing record keeps its persisted state and schema; only the
handler is bound (a warning is logged if a different state_schema
is passed). Handlers live in memory, so register on every start.
Raises:
| Type | Description |
|---|---|
ValueError
|
If the address is invalid or belongs to an llm assistant. |
StateValidationError
|
If a new record's initial state is not strict JSON or violates the schema. |
Source code in orqest/assistants/runtime.py
create
async
¶
Create an llm assistant from a spec.
Inserts the record (state = spec.initial_state), snapshots the spec
version and installs the spec's wakes, all in one transaction, then
emits assistant.lifecycle with action="create".
Returns:
| Type | Description |
|---|---|
AssistantRecord
|
The created record. |
Raises:
| Type | Description |
|---|---|
RuntimeError
|
If the runtime has no agent factory. |
ValueError
|
If the address is invalid, taken or in |
StateValidationError
|
If |
Source code in orqest/assistants/runtime.py
pause
async
¶
Stop processing an assistant until :meth:resume.
Its pending messages wait; recurring wakes are skipped, once wakes
are enqueued and wait in the inbox. Waits for an in-flight run of the
assistant to finish.
Raises:
| Type | Description |
|---|---|
UnknownRecipient
|
If the assistant is missing or retired. |
RuntimeError
|
If called from inside this assistant's own run. |
Source code in orqest/assistants/runtime.py
resume
async
¶
Resume a paused assistant.
Raises:
| Type | Description |
|---|---|
UnknownRecipient
|
If the assistant is missing or retired. |
RuntimeError
|
If called from inside this assistant's own run. |
Source code in orqest/assistants/runtime.py
retire
async
¶
Retire an assistant permanently.
Pending messages become failed (last_error="recipient retired")
and its wakes go inactive. Retired is terminal.
Raises:
| Type | Description |
|---|---|
UnknownRecipient
|
If the assistant is missing or already retired. |
RuntimeError
|
If called from inside this assistant's own run. |
Source code in orqest/assistants/runtime.py
redesign
async
¶
redesign(
address: str,
spec: AssistantSpec,
*,
migrate: Callable[
[dict[str, Any]],
dict[str, Any] | Awaitable[dict[str, Any]],
]
| None = None,
) -> AssistantRecord
Replace an llm assistant's spec with the next version, migrating its state.
The new state is migrate(old_state) (default: unchanged; migrate
may be sync or async) and must satisfy spec.state_schema. The
current state is read and migrated while the address lock is held, so
no run of this assistant can commit in between; the new spec, state,
version snapshot and wakes are then written in one transaction. A
failure anywhere leaves everything as it was.
Returns:
| Type | Description |
|---|---|
AssistantRecord
|
The updated record. |
Raises:
| Type | Description |
|---|---|
UnknownRecipient
|
If the assistant is missing or retired. |
TypeError
|
If the assistant is a code assistant. |
ValueError
|
If |
StateValidationError
|
If the migrated state is invalid. |
RuntimeError
|
If called from inside this assistant's own run. |
Source code in orqest/assistants/runtime.py
rollback
async
¶
Restore an old version's spec and state as a new version.
History stays append-only: the old content is copied to
current + 1.
Returns:
| Type | Description |
|---|---|
AssistantRecord
|
The updated record. |
Raises:
| Type | Description |
|---|---|
UnknownRecipient
|
If the assistant is missing or retired. |
TypeError
|
If the assistant is a code assistant. |
ValueError
|
If |
RuntimeError
|
If called from inside this assistant's own run. |
Source code in orqest/assistants/runtime.py
send
async
¶
send(
sender: str,
recipient: str,
message_type: str,
payload: dict[str, Any],
*,
reply_to: str | None = None,
) -> str
Enqueue a message to an existing, non-retired assistant.
Returns:
| Type | Description |
|---|---|
str
|
The new message id. |
Raises:
| Type | Description |
|---|---|
UnknownRecipient
|
If the recipient is missing or retired. |
ContractViolation
|
If the recipient's contracts reject the message. |
Source code in orqest/assistants/runtime.py
is_owner_turn
async
¶
Whether message_id is the owner's turn in progress.
What to wire into :class:~orqest.compartments.Keeper's is_owner_turn.
True only for an existing message whose sender is in owner_senders (by
default the constructor's) and that an assistant is processing right now, so
neither a message already handled nor one still waiting counts.
Source code in orqest/assistants/runtime.py
list_artifacts
async
¶
Artifacts of every assistant, newest-updated first.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
status
|
set[str] | None
|
Only artifacts with one of these statuses ( |
None
|
Source code in orqest/assistants/runtime.py
search_artifacts
async
¶
Artifacts of any status whose title and intent contain every word of query.
Matching ignores case and compatibility forms (NFKC); at most 20 words and 1000
characters of the query count, limit is clamped to 1..100, and a query that
isn't valid text finds nothing.
Source code in orqest/assistants/runtime.py
pin_artifact
async
¶
Pin address's artifact (it then never expires) or unpin it.
Any artifact can be pinned, a dismissed or expired one keeping what it showed.
Unpinning one that isn't pinned does nothing. Unpinning a pinned one returns a
frozen one to dismissed and a live one to active, with the deadline it
had, so one whose time passed expires at the next poll.
Raises:
| Type | Description |
|---|---|
UnknownArtifact
|
If the assistant has no such artifact. |
Source code in orqest/assistants/runtime.py
delete_artifact
async
¶
Remove address's artifact for real: row, search text, snapshot and view.
For the owner (the application), not a model tool. The freed pages are zeroed
and the write-ahead log truncated, so the text is gone from the file. Emits
ui.artifact.delete. Waits for an in-flight run of the assistant.
The truncation waits only briefly. If another connection keeps the log in use,
the call still succeeds, because the row is gone, but the text stays in the log:
a warning names the artifact, and the truncation is retried on every poll
(tick() / run_forever) until it succeeds, and once at the next open.
A retired assistant's screens aren't emitted again: only ui.artifact.delete.
Raises:
| Type | Description |
|---|---|
UnknownArtifact
|
If the assistant has no such artifact. |
RuntimeError
|
If called from inside this assistant's own run. |
Source code in orqest/assistants/runtime.py
artifact_action
async
¶
artifact_action(
address: str,
artifact_id: str,
action: str,
value: dict[str, Any],
*,
sender: str,
) -> str
Send a user action on address's artifact to that assistant.
Refuses an action the artifact doesn't list in allowed_actions and any action
on a frozen artifact (dismissed, expired, or retired with it), so a stale tap
never reaches the assistant. Otherwise sends it a ui.action message
{artifact_id, action, value}, so voice and touch reach the same place. An
assistant whose address has registered contracts must list ui.action there.
sender is taken as given and is not checked against owner_senders: a
voice or touch action counts as an owner turn only if the application passes a
verified owner sender. Pass anything else and the assistant sees an ordinary
message.
Returns:
| Type | Description |
|---|---|
str
|
The new message id. |
Raises:
| Type | Description |
|---|---|
UnknownArtifact
|
If the assistant has no such artifact. |
ValueError
|
If the action isn't allowed or the artifact is frozen. |
TypeError
|
If |
ContractViolation
|
If the assistant's contracts reject |
UnknownRecipient
|
If the assistant is retired. |
Source code in orqest/assistants/runtime.py
schedule_once
async
¶
Persist a one-shot wake for an assistant.
Returns:
| Type | Description |
|---|---|
str
|
The wake id. |
Raises:
| Type | Description |
|---|---|
UnknownRecipient
|
If the assistant is missing or retired. |
ValueError
|
If |
Source code in orqest/assistants/runtime.py
tick
async
¶
Process due messages for every runnable recipient once.
Recipients are chosen at the start of the tick, so a recipient first
messaged during this tick runs on a later one. Different recipients run
concurrently, and the tick returns when the slowest has finished. A
code assistant's due messages run in FIFO order, claimed and committed
one at a time, at most 20 per tick. An llm assistant claims its due
batch (at most 20) and handles it in one model run committed as one
unit. Each run is bounded by run_timeout_s; with a bus set, live
views are emitted after every commit, each emission bounded by
another run_timeout_s. Handler and model exceptions (including a
timeout, or a CancelledError that is not a cancellation of the
tick) are retried or dead-lettered (for every message of the batch)
and never escape. A recipient whose record cannot be decoded is
skipped (logged once); its messages wait.
Returns:
| Type | Description |
|---|---|
int
|
The number of messages completed. |
Raises:
| Type | Description |
|---|---|
BaseException
|
A |
Exception
|
Errors from the runtime's own commit or fail transactions (database errors) propagate too. This is crash-early: the run loop treats them as fatal. Everything is rolled back and the in-flight message is recovered on restart. |
Source code in orqest/assistants/runtime.py
run_forever
async
¶
Process messages until cancelled, one worker task per recipient.
Unlike :meth:tick, a slow recipient never delays the others: each
runnable recipient with due messages gets its own worker (one run, as
in a tick), never two at once. The loop sleeps up to
poll_interval_s only when no worker started or finished, or the
finished ones completed nothing (see :func:~orqest.assistants.workers.supervise),
so a backlog drains without delay. Cancelling it cancels and awaits
every worker, then the CancelledError propagates; cancel it before
leaving the runtime's async with. It starts by returning every
processing message to pending, so restarting it in the same
open runtime resumes what a cancelled or crashed loop left in flight;
never run it alongside :meth:tick or a second run_forever.
Raises:
| Type | Description |
|---|---|
BaseException
|
Fatal errors, as for :meth: |
Source code in orqest/assistants/runtime.py
spend_blocker ¶
:data:~orqest.assistants.spend.SPEND_EXHAUSTED if the day is used up for address.
The same rule as assistant.spend.exhausted: spent + run_reserve
passes its limit (the cap, or outside priority the cap less the
reserve). Amounts held for runs in flight are ignored, so an application
can use it to refuse a direct model call or to say the budget is used
without a passing run making that false; only the start of an llm run
counts those holds. None without a spend_cap. Synchronous;
now defaults to the runtime's clock.
Source code in orqest/assistants/runtime.py
charge
async
¶
Charge a model call made outside an llm wake to address.
Adds the tokens to its daily token budget and the priced amount to the spend. Safe to call from inside a code handler (it runs outside the wake's transaction).
Returns:
| Type | Description |
|---|---|
float
|
The amount charged ( |
Raises:
| Type | Description |
|---|---|
Exception
|
A failed write propagates, but the amount still counts in this process (the in-memory mirrors were updated first; a restart loses it). A code handler that lets it propagate is retried, and so charges again. |
Source code in orqest/assistants/runtime.py
spend_today
async
¶
Today's spend by address, or None without a spend_cap.
render_view
async
¶
Snapshot one view for a renderer that is (re)loading.
The last-emitted resolution and its event seq (so a renderer that
subscribed first can apply exactly the events after it), else a fresh
resolution with seq 0; see
:meth:~orqest.assistants.live_views.ViewService.render.
A name with the artifact prefix gets a frozen artifact's snapshot or a live artifact's view, and never a fallback view of the raw state.
Raises:
| Type | Description |
|---|---|
UnknownRecipient
|
If the assistant is missing or retired, and the name is not that of a frozen artifact. |
UnknownArtifact
|
If the name has the artifact prefix and no such artifact can be shown (unknown, deleted, or its view or snapshot can't be decoded). |
ValueError
|
If no view is stored and |
Source code in orqest/assistants/runtime.py
list_views
async
¶
Names of address's views (stored, plus default fallbacks for llm), sorted.
Raises:
| Type | Description |
|---|---|
UnknownRecipient
|
If the assistant is missing or retired. |
Source code in orqest/assistants/runtime.py
refresh_views
async
¶
Re-resolve address's views and emit what changed, as after a commit.
For bindings fed by view_context data that changed outside any
run. Takes the address lock (so it waits for an in-flight run) and
emits best-effort like a commit does; without a bus it only checks
the address.
Raises:
| Type | Description |
|---|---|
UnknownRecipient
|
If the assistant is missing or retired. |
RuntimeError
|
If called from inside this assistant's own run. |
Source code in orqest/assistants/runtime.py
UnknownRecipient ¶
The addressed assistant does not exist or is retired.
Wake ¶
A declarative wake-up schedule (daily, weekly, or a single instant).
Attributes:
| Name | Type | Description |
|---|---|---|
kind |
Literal['daily', 'weekly', 'once']
|
Recurrence kind. |
at_time |
time | None
|
Local wall-clock time ( |
weekday |
int | None
|
0=Monday ... 6=Sunday ( |
at |
datetime | None
|
Timezone-aware instant ( |
tz |
str
|
IANA timezone name used to interpret |
reason |
str
|
Free-form note on why the wake exists. |
AssistantSpec ¶
Serializable definition of a durable assistant.
Attributes:
| Name | Type | Description |
|---|---|---|
agent |
AgentSpec
|
LLM agent definition; must use |
state_schema |
dict[str, Any]
|
JSON Schema for the assistant's persistent state. |
initial_state |
dict[str, Any]
|
Starting state; must validate against |
schedule |
list[Wake]
|
Recurring/one-off wakes. |
allowed_contracts |
list[ContractRef]
|
Contracts the assistant may invoke; its only capability channel besides runtime tools. |
version |
int
|
Spec version. |
daily_token_budget |
int | None
|
Tokens (input + output) the assistant may use per
day before its messages wait for the next day; |
ContractRef ¶
Reference to a contract an assistant may send to.
SpendCap
dataclass
¶
SpendCap(
daily: float,
price: Callable[[str | None, RunUsage], float],
priority: frozenset[str] = frozenset(),
reserve: float = 0.0,
run_reserve: float = 0.0,
)
A daily cap on what all assistants spend together.
Orqest does not know a currency: price turns a model name and a run's
usage into an amount, and daily is in the same unit.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
daily
|
float
|
Amount per day across all assistants; must be positive. |
required |
price
|
Callable[[str | None, RunUsage], float]
|
|
required |
priority
|
frozenset[str]
|
Addresses that may spend the reserve. |
frozenset()
|
reserve
|
float
|
The last part of the day only |
0.0
|
run_reserve
|
float
|
The amount held for each llm run in flight (taken when the
run is claimed, released when it is charged). An address is blocked
when one more run would not fit: |
0.0
|
Raises:
| Type | Description |
|---|---|
ValueError
|
Unless |
SpendSummary ¶
What was spent on one budget day.
AssistantRecord ¶
A stored assistant.
Attributes:
| Name | Type | Description |
|---|---|---|
address |
str
|
Unique assistant address. |
kind |
Literal['llm', 'code']
|
|
status |
AssistantStatus
|
Lifecycle status. |
version |
int
|
Current spec version. |
spec |
AssistantSpec | None
|
The spec for llm assistants; |
state |
dict[str, Any]
|
Current persistent state. |
state_schema |
dict[str, Any] | None
|
JSON Schema for |
with_spec ¶
This record as stored after spec and state replaced its own.
Source code in orqest/assistants/store.py
ViewValidationError ¶
A published view has structural problems (unknown block type, invalid data).
Attributes:
| Name | Type | Description |
|---|---|---|
problems |
One line per problem, as reported by
:func: |
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str
|
The view's name. |
required |
problems
|
list[str]
|
The problem lines (non-empty). |
required |
Source code in orqest/assistants/views.py
merge_patch ¶
Apply an RFC 7386 JSON merge patch and return the result.
None deletes a key, nested dicts merge recursively, and any other value
replaces. Neither argument is mutated.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
target
|
dict[str, Any]
|
The document to patch. |
required |
patch
|
dict[str, Any]
|
The merge patch. |
required |
Returns:
| Type | Description |
|---|---|
dict[str, Any]
|
A new dict with the patch applied. |
Source code in orqest/assistants/context.py
next_fire ¶
Return the next fire time strictly after after as a UTC datetime.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
wake
|
Wake
|
The schedule. |
required |
after
|
datetime
|
Timezone-aware reference instant. |
required |
Returns:
| Type | Description |
|---|---|
datetime | None
|
A UTC-aware datetime |
datetime | None
|
that is not in the future. |