PLU-005 · SDK quickstart

Install. Register. Capture one record.

The same shape the dashboard's model-registration flow hands you after a successful call — but reachable as a public page so a new operator can see the wiring before signing in. Every credential on this page is an explicit placeholder; nothing here will call the ledger on its own.

Step 01 · Install

Install the SDK

Drop the SDK into a Node project (Python is illustrative — see note under the Python block). One command lands the module and prints a typecheck so you know the import resolves before you touch a real model.

Node · local sdks/eval-sdk

paste-run

cd sdks/eval-sdk && npm install && node -e "import('@plumbline/eval-sdk').then(m => console.log(typeof m.recordEval))"

Python · polsia (illustrative)

paste-run

# Illustrative — the 'polsia' PyPI package is not published yet.
pip install polsia

Step 02 · Register

Register a model

Registration mints a per-model `pl_…` API key and returns paste-runnable env-var + call pairs for Node and Python. This page shows the SHAPE — once you sign in and run it, the response swaps the placeholders for real values and you paste the snippet straight into your CI.

JSON · response shape

paste-run

// POST /api/models/register
// Headers: cookie session (signed-in users)
// Body:    { name: "<your_model_name>", version: "0.1.0", owner_team: "<your_team>" }
{
  "model_id": "<your_model_id>",
  "api_key":  "<your_api_key>",         // pl_… — shown once, only sha256 is stored
  "snippets": {
    "node":   "POLSIA_API_KEY=… POLSIA_MODEL_ID=… node -e \"import('@plumbline/eval-sdk').then(m=>m.recordEval({input:'hello',output:'hi',version:'0.1.0'}))\"",
    "python": "POLSIA_API_KEY=…\\\n POLSIA_MODEL_ID=…\\\n python -c \"from polsia import record_eval; record_eval(input='hello', output='hi', version='0.1.0')\""
  }
}

JSON · response shape

paste-run

# Same envelope as the Node path; only the snippets.python block differs.
# Drop the values below into the snippet under the Register step.
{
  "model_id":  "<your_model_id>",
  "api_key":   "<your_api_key>",
  "snippets": {
    "node":   "POLSIA_API_KEY=… POLSIA_MODEL_ID=… POLSIA_API_BASE=… node -e \"import('@plumbline/eval-sdk').then(m=>m.recordEval({input:'hello',output:'hi',version:'0.1.0'}))\"",
    "python": "python -c \"from polsia import record_eval; record_eval(input='hello', output='hi', version='0.1.0')\""
  }
}

Step 03 · Capture

Trigger your first evaluation

With the env-var stack set, one command posts an evaluation record against `/api/eval-records`, returning a SHA-256 signature that joins the ledger. Replace `<your_*>` with the values that came back from step 02 — paste, run, watch the ledger row appear in the dashboard.

Node · @plumbline/eval-sdk

paste-run

POLSIA_API_KEY=<your_api_key> \ POLSIA_MODEL_ID=<your_model_id> \ POLSIA_MODEL_VERSION=0.1.0 \ POLSIA_API_BASE=https://plumbline-ai-9.polsia.app \ node -e "import('@plumbline/eval-sdk').then(m => m.recordEval({ input: 'hello', output: 'hi', version: '0.1.0' })).then(console.log)"

Python · polsia (illustrative)

paste-run

# Illustrative Python snippet — the 'polsia' package is not published yet.
POLSIA_API_KEY=<your_api_key> \
POLSIA_MODEL_ID=<your_model_id> \
POLSIA_MODEL_VERSION=0.1.0 \
POLSIA_API_BASE=https://plumbline-ai-9.polsia.app \
python -c "from polsia import record_eval; record_eval(input='hello', output='hi', version='0.1.0')"

Next · Run the flow

Swap the placeholders for real values.

Sign in, register a model, and the snippets above copy with your pl_… key baked in. Drop the key into your CI secret manager before closing the tab — there is no second retrieval.

Choose your next move

Anonymous? You'll be sent through /login first and bounced back to the register-model flow on success.