//DOCS Pantasso Integration

Punk And Pantasso Integration

Punk and Pantasso are separate products that fit together cleanly:

• Pantasso Data Platform is the company data plane. It owns source ingest,

durable company objects, source health, citations, SQL/search/retrieval, support packets, and agent-facing company context.

• Punk is adaptive runtime infrastructure for AI agents. It owns model

routing, runtime governance, side-effect policy, trace/audit of agent calls, failover, optimization, cache/learning, scheduled agents, and run dashboards.

The integration goal is not to merge the products. The goal is to let Pantasso agents use Pantasso for company truth while Punk governs and optimizes the runtime path those agents use to reason and act.

Runtime Boundary

Slack / app user
  -> Pantasso agent profile (@pantasso-sales, @pantasso-research, ...)
  -> Pantasso Data Platform tools for source-backed context
  -> Punk gateway / runtime for model calls, route decisions, policy, and audit
  -> Provider / tool / side effect
  -> Punk trace and dashboard
  -> Pantasso cited answer or artifact

Pantasso should not import Punk packages or store Punk-specific state inside customer source config. Punk should not import Pantasso packages or represent Pantasso as a built-in feature. They integrate over HTTP, SDK calls, API keys, and explicit agent metadata.

Recommended Agent Metadata

Pantasso agents should identify themselves to Punk with stable app, agent, and subject headers:

X-Punk-App: pantasso
X-Punk-Agent: pantasso-sales
X-Punk-Subject: <workspace-id-or-tenant>

Use these Pantasso Slack-facing identities:

Connection Modes

1. Gateway Mode

Point OpenAI-compatible clients at Punk:

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: process.env.PUNK_GATEWAY_URL ?? "http://127.0.0.1:4100/v1",
  apiKey: process.env.PUNK_API_KEY,
  defaultHeaders: {
    "X-Punk-App": "pantasso",
    "X-Punk-Agent": "pantasso-sales",
    "X-Punk-Subject": process.env.PANTASSO_COMPANY_WORKSPACE_ID ?? "company",
  },
});

This governs model routing and creates Punk run records. It does not by itself trace Pantasso tool calls unless the agent also reports those calls through the Punk SDK or routes tools through Punk workflows.

2. SDK/Tool Tracing Mode

Use the Punk SDK around agent tool calls when you need Punk to see side-effect levels, tool arguments, results, feedback, and optimization candidates. Pantasso still owns source-backed retrieval and citations; Punk records runtime behavior and policy.

Use this for:

• Tool-result caching.
• Side-effect declarations.
• Redaction and DLP.
• Approvals.
• Run replay.
• Optimization and learned substitutions.

3. Workflow/Scheduled Agent Mode

Use Punk scheduled agents and workflows when the runtime itself should own a recurring task. In this mode Punk executes the schedule and calls Pantasso over its daemon/CLI/API surface to retrieve company context or write a proposed artifact.

Use this for:

• Daily account, support, or research briefs.
• Recurring source-health checks.
• Agent evaluation runs.
• Human-review queues.
• Multi-agent workflows where Punk governs sequencing and side effects.

First Pilot Layout

On a small customer Droplet, keep filesystem and service ownership explicit:

/opt/pantasso        Pantasso compose kit and image metadata
/srv/pantasso        Pantasso workspace DB, reports, customer files, support packets
/opt/punk            Punk releases, env, systemd metadata
/srv/punk            Punk database and runtime state

Default public surface:

• punk.pdp.cx can remain the Pantasso console for the Punk team workspace.
• Punk can initially bind to 127.0.0.1:4100 and be reached through an SSH

tunnel.

• If a public Punk dashboard is required, expose it on a separate runtime

hostname such as runtime.punk.pdp.cx after auth/readiness checks pass.

Readiness Checks

Pantasso is ready for agents when:

• Source doctor passes for approved sources.
• The durable company workspace DB exists.
• Search and brief commands return cited context.
• Agent profiles exist for enabled roles.
• The support packet has no blockers.
• Slack pollers are enabled only for approved bots/channels.

Punk is ready to govern Pantasso agents when:

• /health passes.
• /api/v1/readiness has no unexpected blockers.
• PUNK_API_KEY and PUNK_ENCRYPTION_KEY are set.
• Dashboard login is required before public exposure.
• Provider keys or tenant BYOK are configured in Punk's hosted control plane.
• A scoped tenant API key exists for Pantasso traffic.
• Runs from X-Punk-App: pantasso appear in the Punk dashboard.

Operating Rule

Pantasso decides what company facts are available and citeable. Punk decides how agent runtime work is routed, governed, optimized, audited, and learned from. Neither product should gain customer-specific assumptions in source code.