> ## Documentation Index
> Fetch the complete documentation index at: https://docs.precipiq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# What are Decision Records in Precipiq?

> A decision record captures every AI action — what the model saw, what it chose, and how confident it was — as an immutable, hash-linked ledger entry.

A decision record is the atomic unit of the Precipiq ledger. Every time an AI agent picks an action — recommend a price, approve a refund, send an email — the SDK writes a record that describes what the model saw, what it decided, and how confident it was. That record is immutable, cryptographically chained to every record before it, and referenceable by any downstream consequence link or liability estimate. The fidelity of this record is what lets a dispute six months later resolve on the ledger rather than in a production log.

## What a decision record contains

Records capture the full decision context without requiring you to expose PII or proprietary prompts. The `inputs` and `outputs` fields are opaque JSON blobs — the SDK never interprets or mutates them, so the record is a byte-for-byte copy of whatever your code passed in.

```json theme={null}
{
  "id": "d5e7a3b0-...-0001",
  "org_id": "o_...",
  "agent_id": "pricing-bot",
  "action_type": "discount_offer",
  "inputs": { "customer_id": "cust_123", "tier": "gold" },
  "outputs": { "discount_pct": 15 },
  "confidence": 0.82,
  "alternatives": [
    { "action": "no_discount", "score": 0.48 },
    { "action": "discount_10", "score": 0.71 }
  ],
  "human_in_loop": false,
  "metadata": { "model_version": "v2.3.1" },
  "timestamp": "2026-04-16T12:34:56.789012Z",
  "prev_hash": "a7b2c3d4...",
  "hash": "e9f0a1b2..."
}
```

The `prev_hash` and `hash` fields are how each record links to its predecessor. See [Hash Chain](/concepts/hash-chain) for the full integrity model.

## Logging a decision

<CodeGroup>
  ```python Python theme={null}
  from precipiq import Precipiq

  pq = Precipiq(api_key="pq_test_demo_key_REPLACE_ME")

  pq.log_decision(
      agent_id="refund-bot",
      action_type="approve",
      inputs={"ticket_id": "t_001", "amount": 99.00},
      outputs={"approved": True},
      confidence=0.93,
      human_in_loop=False,
      metadata={"policy_version": "v3"},
  )
  # In production batching is on — the decision is queued and
  # shipped by the background flusher.  Pass ``enable_batching=False``
  # to the constructor if you need the server receipt in-line.
  ```

  ```typescript TypeScript theme={null}
  import { Precipiq } from 'precipiq';

  const pq = new Precipiq('pq_test_demo_key_REPLACE_ME');

  await pq.logDecision({
    agentId: 'refund-bot',
    actionType: 'approve',
    inputs: { ticket_id: 't_001', amount: 99.0 },
    outputs: { approved: true },
    confidence: 0.93,
    humanInLoop: false,
    metadata: { policy_version: 'v3' },
  });
  ```
</CodeGroup>

<Tip>
  In non-batched mode, `log_decision` / `logDecision` returns a receipt containing the `decision_id` UUID. Store it if you want to create a [consequence link](/concepts/consequence-links) immediately after the decision.
</Tip>

## Design notes

<Steps>
  <Step title="No PII obligation">
    Precipiq never inspects your `inputs` or `outputs`. If your domain requires PII, encrypt or tokenise before passing the dict to the SDK. The record stores exactly what you hand it — nothing more.
  </Step>

  <Step title="Low latency by default">
    Decisions are batched and flushed every 5 seconds (configurable). A Precipiq outage routes unsaved records to a local rotating log — the SDK is safe to install on a hot request path.
  </Step>

  <Step title="Exact byte capture">
    Hashing runs on canonical JSON so clients on different languages and libraries produce the same hash for the same logical record. This is what makes the chain independently verifiable. See [Hash Chain](/concepts/hash-chain) for the serialisation recipe.
  </Step>
</Steps>

## Records are append-only

You cannot mutate a decision record after it is written. A soft-delete redacts the display layer but the record remains on the chain. Because every record carries the hash of its predecessor, tampering with a historical record would break the chain and be detected immediately by a `verify_chain` call.

<Note>
  Once you have a decision record, you can attach financial outcomes to it via [Consequence Links](/concepts/consequence-links). That connection is what turns a raw audit log into a measurable AI P\&L.
</Note>