Skip to main content

Rules

The Rules Library holds hard constraints and preferences that govern agent behavior. Use this resource to define rules, check evidence against them, record violations, and manage versions and sharing.

Access it as client.rules 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: category, severity, hierarchy_scope, enabled, tags, search, linked_ids
for rule in client.rules.list():
    print(rule.id)

Methods​

Core​

list​

list(*, category: str | None = None, severity: str | None = None, hierarchy_scope: str | None = None, enabled: bool | None = None, tags: list[str] | None = None, search: str | None = None, linked_ids: Sequence[str] | None = None, limit: int | None = None) -> SyncPaginator[Rule]

List rules with pagination and filters.

Parameters

  • category (str | None, optional): must | must-not | should.
  • severity (str | None, optional): critical | high | medium | low.
  • hierarchy_scope (str | None, optional): system | org | user | agent.
  • enabled (bool | None, optional): Restrict to enabled (True) or disabled (False) rules.
  • tags (list[str] | None, optional): Filter by tags.
  • search (str | None, optional): Full-text search over description and content.
  • linked_ids (Sequence[str] | None, optional): Only rules that belong to all of these agents and pools.
  • limit (int | None, optional): Maximum number of items to return (default: all matching items).

Returns

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

create​

create(*, description: str, content: str, category: str, severity: str | None = None, hierarchy_scope: str | None = None, enforcement_mode: str | None = None, triggers: Mapping[str, Any] | None = None, tags: Sequence[str] | None = None, enabled: bool | None = None, source: str | None = None, linked_ids: Sequence[str] | None = None) -> Rule

Create a rule.

Parameters

  • description (str): Trigger predicate / one-line summary (required).
  • content (str): Rule body, loaded into context on match (required).
  • category (str): must | must-not | should (required).
  • severity (str | None, optional): critical | high | medium | low.
  • hierarchy_scope (str | None, optional): system | org | user | agent.
  • enforcement_mode (str | None, optional): inject | gate | both.
  • triggers (Mapping[str, Any] | None, optional): Free-form trigger tree ({keywords?, toolName?, embedding?, always?}).
  • tags (Sequence[str] | None, optional): Discoverability tags.
  • enabled (bool | None, optional): Whether the rule starts enabled.
  • source (str | None, optional): Provenance label.
  • linked_ids (Sequence[str] | None, optional): Agents and pools (ids) the rule belongs to.

Returns

  • Rule: The created Rule.

retrieve​

retrieve(rule_id: str) -> Rule

Retrieve a single rule by id.

update​

update(rule_id: str, *, description: str | None = None, content: str | None = None, category: str | None = None, severity: str | None = None, hierarchy_scope: str | None = None, enforcement_mode: str | None = None, triggers: Mapping[str, Any] | None = None, tags: Sequence[str] | None = None, enabled: bool | None = None, linked_ids: Sequence[str] | None = None, change_note: str | None = None) -> Rule

Update a rule and return the updated record.

linked_ids replaces the agents and pools the rule belongs to.

delete​

delete(rule_id: str) -> None

Delete a rule. Raises on failure; returns nothing.

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).

applicable​

applicable(*, user_turn: str | None = None, tool_name: str | None = None, linked_ids: Sequence[str] | None = None) -> dict[str, Any]

Return the enabled rules matching the given turn and tool, for the calling agent.

Also returns the canonical markdown contextBlock for system-prompt injection.

Parameters

  • user_turn (str | None, optional): The user's current turn (matched against trigger keywords).
  • tool_name (str | None, optional): The tool about to be called (matched against trigger toolName).
  • linked_ids (Sequence[str] | None, optional): The calling agent's own id and pools: rules linked to any of them, and rules linked to none, apply.

assess​

assess(rule_id: str) -> dict[str, Any]

Get the rule's quality report: each check and what would raise the score.

The score itself (scoreResult) is kept on the rule by every change.

Returns the report: score (0-100) and grade over the checks that apply, weightAwarded / weightTotal, the failed critical and high counts, and checks. Each check has a status of pass, fail or skipped; a skipped check does not apply to this rule and is not part of the score.

check​

check(tool_name: str, *, args: Mapping[str, Any] | None = None, user_turn: str | None = None, linked_ids: Sequence[str] | None = None) -> dict[str, Any]

Gate a tool call before it runs.

Returns refused: true with the blocking rule when a must-not rule in gate or both enforcement matches the tool (by tool name or keyword trigger); otherwise refused: false.

Parameters

  • tool_name (str): The tool about to be called.
  • args (Mapping[str, Any] | None, optional): Its arguments; a keyword in them also matches.
  • user_turn (str | None, optional): The user's current turn.
  • linked_ids (Sequence[str] | None, optional): The calling agent's own id and pools.

export​

export(**params) -> dict[str, Any]

Export the Rules Library (optionally filtered) as a portable bundle.

import_rules​

import_rules(*, rules: Sequence[Mapping[str, Any]] | None = None, github_url: str | None = None) -> dict[str, Any]

Import rules, as rules owned by the caller: export rows, or a GitHub repository's.

Give exactly one of rules and github_url.

Parameters

  • rules (Sequence[Mapping[str, Any]] | None): Rule rows (the shape export returns).
  • github_url (str | None): A GitHub repository (or a path in it) holding rule files.

Returns

  • dict: imported (new rules), unchanged (rows the caller already has, same description and body), skipped (rows refused) and errors (index and message per skipped row).

list_violations​

list_violations(rule_id: str, *, limit: int | None = None) -> SyncPaginator[RuleViolation]

List a rule's recorded violations, newest first, paging through all of them.

limit caps how many are returned (default: all).

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.

record_violation​

record_violation(rule_id: str, *, attempted_action: str, detected_by: str | None = None, agent_id: str | None = None, thread_id: str | None = None, run_id: str | None = None, evidence: Mapping[str, Any] | None = None) -> RuleViolation

Record a violation against a rule and return it, as list_violations shows it.

Parameters

  • rule_id (str): Target rule id.
  • attempted_action (str): The action that violated the rule (required).
  • detected_by (str | None, optional): What detected the violation: llm, gate or user-report.
  • agent_id (str | None, optional): The agent (its workflow id) that attempted the action.
  • thread_id (str | None, optional): Originating thread id.
  • run_id (str | None, optional): Originating run id.
  • evidence (Mapping[str, Any] | None, optional): Free-form supporting evidence.

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.

restore_version​

restore_version(rule_id: str, version: int) -> Rule

Restore a rule to an earlier version and return the restored record.

retrieve_version​

retrieve_version(rule_id: str, version: int) -> RuleVersion

Retrieve a specific version snapshot of a rule.

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".

versions​

versions(rule_id: str) -> list[RuleVersion]

List the version history of a rule (most recent first).

violations_aggregate​

violations_aggregate(**params) -> dict[str, Any]

Return aggregate violation counts across rules.