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

# Get started with Precipiq

> Install the Precipiq SDK, log your first AI decision, link it to a financial outcome, and check your AI P&L — in about five minutes.

This walkthrough takes you from `pip install` to a decision visible on the dashboard. Pick the SDK you prefer; the REST API is the same underneath.

<Note>
  The tokens used below (`pq_test_demo_key_REPLACE_ME`, `agent_1`, customer
  IDs) are **placeholders**. Replace them with values from your Precipiq
  dashboard before copy-pasting into real code.
</Note>

## Prerequisites

* A Precipiq API key — [grab one from the dashboard](https://dashboard.precipiq.dev/signup).
  Keys look like `pq_live_...` (production) or `pq_test_...` (sandbox).
* Python 3.12+ or Node 18+.
* 30 seconds of network access to `api.precipiq.dev`.

## Steps

<Steps>
  <Step title="Install the SDK">
    Install the Precipiq package for your language.

    <CodeGroup>
      ```bash Python theme={null}
      pip install precipiq
      ```

      ```bash TypeScript theme={null}
      npm install precipiq
      # or: pnpm add precipiq
      # or: yarn add precipiq
      ```
    </CodeGroup>
  </Step>

  <Step title="Log your first decision">
    Create a client and call `log_decision` / `logDecision`. The call returns a
    receipt containing the decision's UUID and its position on the hash chain.

    <CodeGroup>
      ```python Python theme={null}
      # demo.py
      from precipiq import Precipiq

      # ``enable_batching=False`` for the demo so the call ships
      # synchronously and ``log_decision`` returns the server receipt
      # instead of ``None``.  In production, leave batching on for
      # throughput and call ``pq.flush()`` at shutdown.
      pq = Precipiq(
          api_key="pq_test_demo_key_REPLACE_ME",
          enable_batching=False,
      )

      receipt = pq.log_decision(
          agent_id="pricing-bot",
          action_type="discount_offer",
          inputs={"customer_id": "cust_123", "tier": "gold"},
          outputs={"discount_pct": 15},
          confidence=0.82,
          human_in_loop=False,
      )
      # ``receipt`` is a dict keyed by the server's snake_case schema.
      print("decision id:", receipt["decision_id"])
      print("chain hash:", receipt["hash"])
      ```

      ```typescript TypeScript theme={null}
      // demo.ts
      import { Precipiq } from 'precipiq';

      // ``enableBatching: false`` for the demo so the call ships
      // synchronously and returns a receipt.  In production, leave
      // batching on and call ``pq.flush()`` at shutdown.
      const pq = new Precipiq('pq_test_demo_key_REPLACE_ME', {
        enableBatching: false,
      });

      const receipt = await pq.logDecision({
        agentId: 'pricing-bot',
        actionType: 'discount_offer',
        inputs: { customer_id: 'cust_123', tier: 'gold' },
        outputs: { discount_pct: 15 },
        confidence: 0.82,
        humanInLoop: false,
      });

      if (receipt) {
        console.log('decision id:', receipt.decisionId);
        console.log('chain hash:', receipt.hash);
      }
      ```
    </CodeGroup>

    Run the script. You should see a UUID and a 64-character SHA-256 hash
    printed to stdout within \~200 ms.
  </Step>

  <Step title="See it in the dashboard">
    Open [dashboard.precipiq.dev](https://dashboard.precipiq.dev), sign in with
    the same API key, and the decision appears at the top of the **Decisions**
    timeline — usually within one second of the SDK call, thanks to the
    dashboard's WebSocket stream.

    You should see a row whose timestamp matches the `receipt.timestamp` your
    SDK call just returned, with the `pricing-bot` agent label and a confidence
    badge at 82%.
  </Step>

  <Step title="Wrap a function with track">
    In production you rarely call `log_decision` directly. Instead, wrap the
    function that makes the decision — the SDK captures inputs, outputs, and
    any exception automatically.

    <CodeGroup>
      ```python Python theme={null}
      @pq.track(agent_id="pricing-bot", action_type="discount_offer")
      def compute_discount(customer_id: str, tier: str) -> dict:
          # Your real business logic:
          pct = 15 if tier == "gold" else 5
          return {"discount_pct": pct}

      compute_discount("cust_456", "silver")
      # The decision, inputs, and outputs are recorded on every call.
      ```

      ```typescript TypeScript theme={null}
      const computeDiscount = pq.track(
        'pricing-bot',
        'discount_offer',
        async (args: { customerId: string; tier: string }) => {
          const pct = args.tier === 'gold' ? 15 : 5;
          return { discountPct: pct };
        },
      );

      await computeDiscount({ customerId: 'cust_456', tier: 'silver' });
      ```
    </CodeGroup>
  </Step>

  <Step title="Link the decision to a financial outcome">
    When the customer gets charged — via a Stripe webhook, an internal event,
    or any other billing system — link the decision to the resulting financial
    event so the AI P\&L can attribute dollars.

    <CodeGroup>
      ```python Python theme={null}
      # ``receipt`` came from step 2.
      # The second arg is the ``financial_event_id`` returned by your Stripe integration.
      pq.link_outcome(
          receipt["decision_id"],
          "fev_abc",
          correlation_strength=1.0,       # 0..1 — strongest when directly caused
          link_type="revenue",            # "revenue" | "cost" | "liability" | "neutral"
      )
      ```

      ```typescript TypeScript theme={null}
      if (receipt) {
        await pq.linkOutcome(
          receipt.decisionId,
          'fev_abc',
          {
            correlationStrength: 1.0,
            linkType: 'revenue',
          },
        );
      }
      ```
    </CodeGroup>

    For events that come from Stripe, the built-in webhook receiver auto-creates
    the financial event and the attribution engine proposes the link — see the
    [Stripe integration guide](/integrations/stripe).
  </Step>

  <Step title="Check your AI P&L">
    Query aggregated P\&L for any date range. The same numbers appear on the
    **P\&L** tab of the dashboard, live-updated as new events stream in.

    <CodeGroup>
      ```python Python theme={null}
      pnl = pq.get_ai_pnl(start="2026-04-01", end="2026-04-30")
      # ``pnl`` is a dict keyed by the server's snake_case schema.
      if pnl is not None:
          print(pnl["total_revenue_attributed"], pnl["currency"])
          print(pnl["net_ai_impact"])
      ```

      ```typescript TypeScript theme={null}
      const pnl = await pq.getAiPnl({ start: '2026-04-01', end: '2026-04-30' });
      if (pnl) {
        console.log(pnl.totalRevenueAttributed, pnl.currency);
        console.log(pnl.netAiImpact);
      }
      ```
    </CodeGroup>
  </Step>
</Steps>

In about five minutes you now have a live SDK install, a chain-linked decision on the ledger, a linked financial event, and an attribution visible on the dashboard.

<Card title="Next: understand the data model" href="/concepts/decision-records" icon="book">
  Concepts — the six record types and how they compose.
</Card>