Skip to main content

Preferences

Agent Preferences.

Access it as client.preferences on a Strongly client, or the same path on AsyncStrongly with await. All methods exist on both with identical signatures.

Quick start​

from strongly import Strongly

client = Strongly()

# List (auto-paginates as you iterate)  # filters: search, category, preference_source, tags, include_superseded
for preference in client.preferences.list():
    print(preference.id)

Methods​

Core​

list​

list(*, search: str | None = None, category: str | None = None, preference_source: str | None = None, tags: list[str] | None = None, include_superseded: bool | None = None, limit: int | None = None) -> SyncPaginator[Preference]

List preferences with pagination and filters.

Parameters

  • search (str | None, optional): Full-text search over key and value.
  • category (str | None, optional): Filter by category.
  • preference_source (str | None, optional): explicit | learned | inferred | imported | manual.
  • tags (list[str] | None, optional): Filter by tags.
  • include_superseded (bool | None, optional): Include archived (superseded) rows.
  • limit (int | None, optional): Maximum number of items to return (default: all matching items).

Returns

  • SyncPaginator[Preference]: A paginator yielding Preference objects.

create​

create(*, key: str, value: Any, category: str | None = None, preference_source: str | None = None, confidence: float | None = None, evidence: str | None = None, tags: Sequence[str] | None = None, linked_ids: Sequence[str] | None = None) -> Preference

Create a preference (key and value required).

Upsert-by-key semantics: writing the same key+value twice is a no-op; a new value archives the old row in the supersedes chain. Alias of set.

Parameters

  • key (str): Preference key (e.g. preferred_language).
  • value (Any): Preferred value.
  • category (str | None, optional): Optional grouping label.
  • preference_source (str | None, optional): Origin of the preference (explicit, learned, inferred, imported, manual).
  • confidence (float | None, optional): Confidence score in [0, 1].
  • evidence (str | None, optional): Citation backing the preference.
  • tags (Sequence[str] | None, optional): Optional tags.
  • linked_ids (Sequence[str] | None, optional): Agents and pools the preference belongs to. Setting a key again without them keeps the ones it had.

set​

set(key: str, value: Any, *, category: str | None = None, preference_source: str | None = None, confidence: float | None = None, evidence: str | None = None, tags: Sequence[str] | None = None, linked_ids: Sequence[str] | None = None) -> Preference

Upsert a preference by key (idempotent on owner+key).

Writing the same key+value twice is a no-op; writing a new value archives the old row in the supersedes chain. Convenience over create; both hit the same endpoint.

retrieve​

retrieve(preference_id: str) -> Preference

Retrieve a preference by id.

by_key​

by_key(key: str) -> Preference

Look up the current preference for a given key.

update​

update(preference_id: str, *, value: Any = None, category: str | None = None, preference_source: str | None = None, confidence: float | None = None, evidence: str | None = None, tags: Sequence[str] | None = None, linked_ids: Sequence[str] | None = None) -> Preference

Update a preference and return it as saved.

Only the arguments given change. A new value supersedes the current one (the old value is kept as history): the result is the new value's record, with its own id, and fields left out carry forward. Other changes edit the preference in place. linked_ids replaces the agents and pools it belongs to.

delete​

delete(preference_id: str) -> None

Delete a preference by id.

The current value goes with its earlier values; a superseded value goes alone.

Other​

add_member​

add_member(resource_id: str, *, user_id: str, role: str) -> Permissions

Share the resource with a user.

Parameters

  • resource_id (str): The resource's id.
  • user_id (str): The user to share it with.
  • role (str): "editor" (use and change it) or "user" (use it only; types without a use-only tier, such as knowledge bases, take "editor" only).

forget​

forget(key: str) -> dict[str, Any]

Forget a preference by key: its current value and its earlier values.

Returns {"removedId": ...}, or {"removedId": None} when the key had no value.

permissions​

permissions(resource_id: str) -> Permissions

Return who can reach the resource: its owner, members and their roles, and visibility.

Parameters

  • resource_id (str): The resource's id.

remove_member​

remove_member(resource_id: str, user_id: str) -> None

Stop sharing the resource with a user.

Parameters

  • resource_id (str): The resource's id.
  • user_id (str): The user to stop sharing it with.
search(*, user_turn: str, category: str | None = None, limit: int | None = None, tags: str | None = None, linked_ids: Sequence[str] | None = None) -> dict[str, Any]

Find the preferences relevant to a turn, with the context_block for a prompt.

Returns {preferences, context_block}.

Parameters

  • user_turn (str): The message the preferences are for.
  • category (str | None, optional): Only this category's.
  • tags (str | None, optional): Only preferences with one of these tags (comma-separated).
  • linked_ids (Sequence[str] | None, optional): Only preferences in one of these pools.

set_visibility​

set_visibility(resource_id: str, visibility: str) -> Permissions

Make the resource public (every user can find and use it) or private.

Parameters

  • resource_id (str): The resource's id.
  • visibility (str): "public" or "private".