Prepare
Read the canonical session, resolve the project and every matching configuration, bound the transcript, and load current tags.
Preview Insight plugin contract · in development Bring your logic.
Bring your logic.
Keep the control plane.
Insight processors run as stateless services behind a small gRPC contract. The gateway sends bounded, user-visible transcript text and policy context; the plugin returns tagged insights with source IDs. The gateway keeps session parsing, project scope, provenance, and storage.
INSIGHTS.V1 SERVICE BUILDING
serviceInsightsServicev1
rpcGenerateInsightsunary
inputparsed transcript + tags + policybounded
outputinsights + source ids + usagetyped
healthservice + versiontestable
transport: gRPC over persistent HTTP/2
01 The bridge
A narrow contract across the insight lifecycle.
The plugin does not need Pi storage knowledge, database access, or project-memory ownership. It receives a typed request and returns a typed result.
Generate
Apply the configured insight logic and return summaries, tagged insights, source item IDs, proposed tags, usage, and warnings.
Account
Validate sources, redact results, persist the run and its revision, then materialize accepted knowledge for the repository.
02 Capability map
A stable boundary, with the integration still underway.
The service contract and control-plane implementation are being built together. This page describes that implemented direction without claiming a production processor is already available.
GenerateInsights RPC
Receive a bounded parsed transcript, current tag registry, configuration instructions, summary flags, and a durable run identity.
Health RPC
Expose service name and version so operators can test a registered gRPC target before a nightly session run depends on it.
Service registry
Manage gRPC targets, TLS or trusted-network plaintext, optional server name, timeout, active state, and reusable HTTP/2 connections.
Scoped configurations
Attach independent policies to global, tenant, or project scope with instructions, input bounds, tags, summaries, and revisions.
Tag governance
Send active tags and descriptions to processors, count usage, and decide per configuration whether new tags may be proposed.
Run provenance
Persist configuration revision, input hash, insight source IDs, usage, warnings, errors, timestamps, and idempotent results.
03 Boundaries Flexible for the processor.
Flexible for the processor.
Controlled by the gateway.
The gateway parses canonical session JSONL and sends only user and assistant text. Thinking blocks and raw tool records do not cross the processor boundary.
The gateway selects every matching active configuration by global, tenant, and project scope. The processor never decides tenancy.
Returned source IDs are accepted only when they refer to transcript items in the request. Runs keep configuration revision and input hash.
The gateway normalizes tags, redacts and bounds returned content, stores results, and materializes accepted knowledge into the project journal.
Build target Current service contract Implement two RPCs.
Implement two RPCs.
Leave the control plane to the gateway.
A processor implements generation and health. It can use any model stack or deterministic rules internally, as long as it returns the versioned response contract and remains stateless with respect to gateway ownership.
# service insights.v1.InsightsService # methods GenerateInsights(request) Health(empty) Explore configurations and runs →