Tenant-aware bulk writes & recall

Bulk-write and recall per tenant from the public Python API without hand-constructing Policy and Principal objects at every call site.

Python

remember_many() routes each record to its normalized tenant and still writes through Heartwood.remember() — so you get provenance signatures, source-span hashes, encrypted content, deletion-lineage registration, audit rows, and index updates.

python

from heartwood import Heartwood

db = Heartwood(path="heartwood.db", tenant="tenant:ops")

db.remember_many(
    [
        {
            "tenant": "acme-payments",
            "subject": "acme-payments:audit",
            "content": "Acme Payments reviews must preserve audit details and source spans.",
            "created_by": "owner:operator",
            "classification": "internal",
        },
        {
            "tenant": "northwind-retail",
            "subject": "northwind-retail:auth",
            "content": "Northwind Retail auth incidents require finance review.",
            "classification": "confidential",
            "roles": ["finance"],
        },
    ],
    default_created_by="agent:bulk",
)

out = db.recall_for_tenant(
    "northwind-retail",
    "who reviews auth incidents?",
    principal_id="agent:orchestrator",
    roles=["finance"],
    clearance="confidential",
    k=5,
)

Convenience helpers

python

from heartwood import normalize_tenant, policy_from, principal_from

tenant = normalize_tenant("acme-payments")            # tenant:acme-payments
policy = policy_from({"classification": "confidential", "roles": "finance"})
principal = principal_from("agent:orchestrator",
                           tenant="northwind-retail",
                           clearance="confidential")

JSONL bulk import

The CLI accepts JSONL objects or a JSON list/object with records[]. The report includes tenant_counts, per-record IDs, source coverage, and record-level errors. Add --stop-on-error to fail on the first malformed record.

powershell

python -m heartwood.cli bulk-remember `
  --input .\records.jsonl `
  --db .\heartwood.db `
  --tenant tenant:ops `
  --created-by agent:bulk `
  --output .\heartwood-bulk-report.json

Adapted from docs/integrations/api-ergonomics.md in the open-source core.

Install Heartwood View source on GitHub