Skip to main content

Policies

Turn a policy document into controls that a Guardian can enforce. Ingestion is asynchronous. The SDK returns a typed handle immediately, then lets you refresh status, inspect nodes, finalize the policy, and create later versions.

Status: Beta Companion docs: Policies API · Guardians API · Testing and CI Source of truth: Policies API. This guide is the Python SDK projection.

Ingest and wait for ready​

import time
from trinitite import Trinitite

tr = Trinitite(env="prod")

policy = tr.policies.ingest(
    """
# Refund policy

Customers may request a refund within 30 days.
Refunds over $500 require human review.
    """.strip(),
    title="refund-policy",
    description="Rules for customer refunds.",
    kind="policy",
    frameworks=["soc2"],
    controls=["soc2:CC6.1"],
)

while policy.ingestion_status in {"pending", "ingesting"}:
    time.sleep(1)
    policy = policy.status()

if policy.ingestion_status != "ready":
    raise RuntimeError(f"Policy ingestion ended as {policy.ingestion_status}")

print(policy.document_id)
print(policy.node_count)

tr.policies.ingest(...) returns PolicyNodeHandle. Its document_id uses the pdoc_ prefix. Poll policy.status() until ingestion_status is ready or failed.

Inspect the decomposed nodes​

nodes_response = policy.nodes()
for node in nodes_response.body.get("nodes", []):
    print(node.get("node_id"), node.get("text"))

Collections such as nodes, versions, and edit history return Response. Read their JSON through .body and check .ok or .status before using it.

versions = policy.versions()
history = policy.edit_history(entity_type="node")

assert versions.ok
assert history.ok

Framework and control links are accepted for documents with kind="policy". They are applied after decomposition, so inspect nodes only after the policy reaches ready.

Finalize the policy​

Finalization locks the policy version. It can also create tests and start Guardian training.

finalized = policy.finalize(
    notes="Approved by the policy owner.",
    auto_generate_tests=True,
    auto_generate_variations=True,
    auto_train=True,
    guardian_id="refund-guardian",
)

assert finalized.ok
print(finalized.document_id)

To bind an existing suite, pass test_suite_id. To create one during finalization, pass create_test_suite=True and test_suite_name.

Create a new version​

Reingestion preserves the document identity and creates a new version.

policy = policy.reingest(
    """
# Refund policy

Customers may request a refund within 45 days.
Refunds over $500 require human review.
    """.strip(),
    change_summary="Extended the refund window to 45 days.",
)

while policy.ingestion_status in {"pending", "ingesting"}:
    time.sleep(1)
    policy = policy.status()

Find and list policies​

policy = tr.policies.get("refund-policy").status()
all_policies = tr.policies.list()

for item in all_policies.body.get("documents", []):
    print(item["document_id"], item["name"], item["status"])

get(...) accepts a pdoc_ id or a policy name. Name lookup uses the first matching document returned by the policy list.

Next steps​

  • Guardians: understand the runtime Guardian that enforces a finalized policy.
  • Testing and CI: exercise verdict branches and create scheduled gates.
  • Traces and graph: walk from a policy node to controls, assets, and decisions.
Last updated on