Punk Concepts
This page defines the mental model shared by the docs, dashboard, SDK, and API.
One-Sentence Model
Punk observes every agent run, governs what the agent can do, structures web context into machine-readable SOM, learns repeated work, proves optimized paths through replay and shadow evaluation, and routes future work through the cheapest safe path.
Runtime Loop
Observe -> Govern -> Structure -> Optimize -> Prove -> Route -> Audit -> Learn| Step | Meaning |
|---|---|
| Observe | Capture the request, model call, tool calls, web fetches, side effects, costs, latency, and output. |
| Govern | Evaluate identity, trust, policies, side-effect level, approvals, and tenant mode. |
| Structure | Normalize prompts, tools, outputs, and web pages. Web pages become SOM snapshots. |
| Optimize | Check caches, fingerprints, patterns, artifacts, and route confidence. |
| Prove | Use replay, shadow evaluation, and promotion gates before serving an optimized path live. |
| Route | Select live, cache, artifact, SOM cache, tool cache, hybrid, blocked, or approval-required behavior. |
| Audit | Persist route explanations, policy decisions, trace events, side effects, approvals, and audit records. |
| Learn | Discover patterns, synthesize artifacts, update confidence, detect drift, and improve routing. |
Core Entities
| Entity | What it is |
|---|---|
| Tenant | Isolation boundary for data, settings, keys, runs, policies, caches, and artifacts. |
| App | Logical application sending traffic through Punk. |
| Agent | Runtime actor with trust tier, trust score, tags, and audit identity. |
| Subject | Pseudonymous end-user or scope used as a cache-key safety dimension. |
| Run | One model request or runtime interaction observed by Punk. |
| Trace event | Append-only event in the run ledger. |
| Route explanation | Human-readable and machine-readable reason for the selected route. |
| Pattern | Cluster of repeated runs grouped by fingerprint and behavior. |
| Artifact | Verified deterministic or semi-deterministic replacement for repeated work. |
| Evaluation | Replay, shadow, or live confidence evidence for an artifact. |
| Approval | Human decision record for policy exceptions or artifact promotions. |
| SOM snapshot | Semantic Object Model representation of a web page. |
| Audit event | Governance evidence: actor, action, decision, policy, reason, metadata. |
Routes
| Route | Meaning |
|---|---|
live | Request was served by the live provider. |
exact_cache | Identical normalized request was served from cache. |
semantic_cache | Semantically equivalent request was served from cache. |
tool_cache | Read-only tool result was reused. |
som_cache | Web page semantic snapshot was reused. |
plan_cache | Stable plan was reused while fresh reads may still run. |
artifact | Promoted deterministic artifact served the response. |
hybrid_artifact | Artifact handled part of the route with model fallback. |
blocked | Policy denied the request. |
Every optimized or blocked response should have a route explanation.
Gateway Modes
| Mode | Behavior |
|---|---|
optimize | Punk may cache, serve artifacts, enforce policy blocks, and record savings. |
observe | Punk records what it would have done, but always returns live provider responses and does not block. Savings are tracked as ghost savings. |
Gateway mode is pinned to API keys. Use observe mode for pilots where trust must be earned before optimization affects traffic.
Side-Effect Levels
| Level | Meaning | Default behavior |
|---|---|---|
| 0 | Pure computation | Cacheable and replayable. |
| 1 | Read-only external call | Cacheable with TTL and subject/auth scope. |
| 2 | Reversible or idempotent write | Requires idempotency/rollback thinking. |
| 3 | User-visible write | Not cached; suppressed in replay/shadow; policy-gated. |
| 4 | High-impact write | Live plus approval by default. |
Undeclared tools default conservatively to level 3.
SOM
SOM means Semantic Object Model. It is Punk's structured representation of web pages for agents:
- Semantic regions such as navigation, main, form, header, footer, dialog.
- Semantic elements such as links, buttons, inputs, tables, headings, paragraphs.
- Stable element IDs.
- Explicit actions such as click, type, select, and submit.
- Metadata for byte counts and token-savings estimates.
SOM lets Punk cache, diff, replay, and reason over web context without sending raw HTML to a model.
Web sessions build on SOM. A session holds a page state, executes protocol-level actions against stable SOM element IDs, and recompiles the resulting page. type and select are session-local pure actions, click is usually a read/navigation action, and submit is a user-visible write that must be governed like any other side effect. Form-button clicks should be reviewed as submit-sensitive behavior.
Artifact Lifecycle
Common states:
observed: repeated pattern detected.candidate: candidate artifact exists.replay_passed/replay_failed: historical proof result.shadowing/shadow_failed: live shadow evidence.promoted: eligible for live route use.canary: limited rollout when canary mode is enabled.stable: default for matched traffic.degraded: confidence lowered.quarantined: blocked from runtime use.retired: intentionally removed or superseded.
Promotion should be evidence-based, policy-aware, auditable, and reversible.
Approvals
Approvals cover two high-frequency human decisions:
- Policy exception: a request matched
requiresApproval. - Artifact promotion: a candidate passed gates and needs operator sign-off.
Approvals are visible in the dashboard, API, and PunkBar. Decisions are written to audit.