gopact-examples

README

🧪 gopact-examples

Chinese documentation: README_zh.md

Executable examples for the redesigned gopact API.

Go 1.27+ only. This project uses generic methods and therefore requires Go 1.27 or later.

Go 1.27.0 is not yet available from the public toolchain servers, so CI is temporarily pinned to 1.27.0-rc.2. New gopact-examples releases use stable semantic versions; no further project RC releases will be published. Until the final toolchain is available, the local commands below select the public go1.27rc2 toolchain explicitly.

The manually dispatched source E2E workflow requires reviewed 40-character commit SHAs for all three repositories, checks out those exact commits, prints them, and joins the repositories with a temporary Go workspace. The ordinary module test job consumes the immutable stable versions declared by the examples module with GOWORK=off; the required source-compatibility job separately tests the coordinated source tree.

The release order is core → ext modules → examples. This module pins the approved immutable dependency tags and must pass with GOWORK=off before its own release tag is created.

Default example runs are intentionally offline.

Quickstarts

Example	What it teaches
quickstart/model-basic	Implement and invoke the minimal gopact.Model contract
quickstart/workflow-basic	Build and run a typed Workflow with observable events
quickstart/react-basic	Connect a model and tool through the ReAct Agent

Concepts

Example	What it teaches
concepts/durable-resume	Resume one interrupted Run from its checkpoint
concepts/run-control	Retry or fork a failed Run into a new Run with source lineage
concepts/session-correlation	Correlate independent Runs with a Session, then inspect and resume one selected Run

The durable-resume example keeps only the public interrupt/resume path. Fresh-process decoding, fencing, crash windows, and side-effect idempotency belong to the core and Store integration suites rather than a quick conceptual example. MemoryStore keeps this example offline; replace it with a durable Store before relying on process recovery.

The run-control example leaves the failed source Run immutable. Retry replays one failed node activation into a new Run, while Fork starts another new Run from a replay-safe root with a patched workflow input. Both new Runs retain SourceRunID lineage.

The session query lists related Runs. Snapshot and resume select a mandatory RunID; there is no Session snapshot. The shared workflow.MemoryStore holds process-lifetime execution checkpoints and journal records, not semantic Memory, and is only for tests or short-lived processes. Use SQLite on one machine or from processes that safely share one local database file; use a distributed database Store with atomic Claim and fencing for multiple hosts.

Integrations

Example	What it teaches
integrations/otel	Map Workflow identity and events onto a caller-owned OpenTelemetry span
integrations/mem0	Retrieve semantic Memory explicitly and build Agent Context in application code

OpenTelemetry integration

Use integrations/otel when an application already owns OpenTelemetry setup. The example projects Workflow domain Events onto the run span, mapping SessionID to gen_ai.conversation.id, RunID to gopact.run.id, and the Workflow definition ID to gopact.workflow.name. It separately wraps an application adapter with an infrastructure span; that span does not manufacture a Workflow Event.

This keeps telemetry identity out of the domain Event and storage schema, leaves the core free of an OpenTelemetry dependency, and works with any SDK exporter. Both projections use the invocation context.Context; with the OpenTelemetry no-op provider they add no runtime telemetry.

Mem0 integration

Use integrations/mem0 when an Agent needs semantic Memory from Mem0 or a compatible HTTP service. It solves retrieval and scope mapping with an explicit typed topology:

load-memory (HTTP I/O) -> build-model-request (pure) -> model

The application constructs the Agent Context that determines what the model sees; Memory is one input to that Context, not a framework-owned container or provider interface. Retrieved Memory is external, mutable, and untrusted. The example places a fixed application-owned policy in the system role, puts recalled Memory in a separate user-role message labeled as untrusted evidence, and keeps the current user message last. Ordinary workflow input carries user text rather than a role-bearing model message, so request data cannot select a higher-trust role. Memory is never promoted to a system instruction.

The retrieval node reads SessionID and Workflow RunID from workflow.RunInfoFromContext; business Context does not duplicate execution metadata. User and Agent identity live in application-owned memoryWorkflowConfig, outside the ordinary workflowInput. The runnable demo uses fixed values; a real service must derive them from authenticated server-side state rather than copying fields from a request body. The application also assigns SessionID through RunOptions after establishing the caller's scope.

Application identity	Mem0 / model mapping
Authenticated UserID in application config	user_id
Application-owned Agent identity	agent_id
Application-assigned SessionID	Mem0 run_id
Workflow RunID	gopact.workflow.run_id in ModelRequest.Metadata for provenance

Advantages: the I/O boundary is visible in the Workflow, provider policy stays in application code, and no Mem0 dependency enters core or ext. Limitations: role separation is defense in depth, not complete prompt-injection protection or authorization. The application still owns identity authentication, scope authorization, result selection, provenance validation, ranking, prompt construction, HTTP compatibility, and failure policy. The minimal client demonstrates one POST /search contract rather than a complete Mem0 SDK. To prevent API-key disclosure, it rejects every redirect, including same-origin redirects; configure the final endpoint URL directly.

The deterministic example uses an offline response. To run the external smoke test with its 15-second timeout, optionally load the repository-local .env first:

set -a; [ ! -f .env ] || . ./.env; set +a
GOTOOLCHAIN=go1.27rc2 MEM0_INTEGRATION=1 go test -tags=integration ./integrations/mem0 -run TestMem0Smoke -count=1 -v

MEM0_BASE_URL defaults to http://localhost:8888; MEM0_API_KEY is optional.

Run all examples

From a published checkout:

GOTOOLCHAIN=go1.27rc2 GOWORK=off go mod download
GOTOOLCHAIN=go1.27rc2 GOWORK=off go test -count=1 ./...

The pre-tag source E2E workflow instead creates a temporary workspace over the three coordinated source checkouts and runs:

GOTOOLCHAIN=go1.27rc2 go test ./...