Prepare
The gateway reads the canonical session. It resolves the project and every matching configuration. It bounds the transcript and loads current tags.
Preview Insight plugin contract · in development Build an
Build an
insight service.
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 Service interface
A small contract defines how insights are produced.
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
The processor applies the configured insight logic. It returns summaries, tagged insights, source item IDs, proposed tags, usage, and warnings.
Account
The gateway validates sources and redacts results. It persists the run and its revision. It materializes accepted knowledge for the repository.
02 Capability map
The interface is stable. The integration is still underway.
The service contract and control-plane implementation are being built together. This page describes that direction. It does not claim a production processor is already available.
GenerateInsights RPC
The processor receives a bounded parsed transcript, the 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. Decide per configuration whether processors may propose new tags.
Run provenance
Persist configuration revision, input hash, insight source IDs, usage, warnings, errors, timestamps, and idempotent results.
03 Boundaries The processor generates insights.
The processor generates insights.
The gateway checks the results.
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. It redacts and bounds returned content. It stores results and materializes accepted knowledge into the project journal.
Build target Current service contract Implement two RPCs.
Implement two RPCs.
The gateway manages sessions and results.
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 →