README
¶
DriftlessAF
DriftlessAF is Chainguard's foundational agentic framework for building AI-powered automation and resilient GitHub reconcilers.
Features
This project includes the following Go modules and functionality.
Agentic AI infrastructure
- AI executors: Production-ready executors for Google Gemini and Anthropic Claude models.
- Evaluation framework: Testing and monitoring agent quality with comprehensive metrics.
- OpenTelemetry metrics: Built-in observability for AI operations.
- Prompt building: Utilities for constructing and managing prompts.
- Tool calling: Helpers for function/tool calling with Claude and Gemini.
- Result parsing: Structured output extraction from model responses.
Find more information in the agents README.
Reconciler infrastructure
Production-ready reconciler infrastructure based on the Kubernetes reconciliation pattern, adapted for GitHub automation:
- Workqueue system: GCS-backed state persistence with retry, exponential
backoff, and concurrency control (
workqueue/). Find more information in the workqueue README. - Reconcilers: Process GitHub pull requests, repository file paths, APK
packages, and OCI artifacts (
reconcilers/). Find more information in the reconciler README.
Installation
go get chainguard.dev/driftlessaf@latest
Usage
See the package documentation for examples and the API reference.
Examples
See the examples README for more information.
Build
This repository contains two Go modules — the root chainguard.dev/driftlessaf
library and the chainguard.dev/driftlessaf/examples module. Build and test each
from its own directory.
Go 1.25.8 or newer is required, as specified in both go.mod files.
Root library:
go build ./...
go test ./...
Examples:
cd examples
go build ./...
go test ./...
License
Directories
¶
| Path | Synopsis |
|---|---|
|
agents
|
|
|
agenttrace
Package agenttrace provides tracing infrastructure for AI agent interactions.
|
Package agenttrace provides tracing infrastructure for AI agent interactions. |
|
agenttrace/payloadcrypt
Package payloadcrypt seals the sensitive free-text fields of an agent trace (prompt, completion, tool params/results, reasoning) before they leave the emitting process, so the CloudEvent — and the BigQuery row the recorder derives from it — carries ciphertext rather than plaintext.
|
Package payloadcrypt seals the sensitive free-text fields of an agent trace (prompt, completion, tool params/results, reasoning) before they leave the emitting process, so the CloudEvent — and the BigQuery row the recorder derives from it — carries ciphertext rather than plaintext. |
|
agenttrace/payloadcrypt/kmsseal
Package kmsseal provides the Cloud KMS-backed wrap for payloadcrypt.
|
Package kmsseal provides the Cloud KMS-backed wrap for payloadcrypt. |
|
anthropicauth
Package anthropicauth builds the anthropic.Client used by the Claude agent and judge executors, selecting the authentication backend from a caller-supplied Config.
|
Package anthropicauth builds the anthropic.Client used by the Claude agent and judge executors, selecting the authentication backend from a caller-supplied Config. |
|
evals
Package evals provides observers and validation helpers for evaluating completed agent traces.
|
Package evals provides observers and validation helpers for evaluating completed agent traces. |
|
evals/report
Package report provides report generation functionality for evaluation results.
|
Package report provides report generation functionality for evaluation results. |
|
evals/testevals
Package testevals provides a testing.T adapter for the evals framework.
|
Package testevals provides a testing.T adapter for the evals framework. |
|
executor/claudeexecutor
Package claudeexecutor provides a generic executor for Claude-based agents that reduces boilerplate while maintaining flexibility for agent-specific logic.
|
Package claudeexecutor provides a generic executor for Claude-based agents that reduces boilerplate while maintaining flexibility for agent-specific logic. |
|
executor/googleexecutor
Package googleexecutor provides a generic Google AI (Gemini) executor for AI agents.
|
Package googleexecutor provides a generic Google AI (Gemini) executor for AI agents. |
|
executor/internal/execshared
Package execshared holds behavior shared by the executor implementations (claudeexecutor, googleexecutor, openaiexecutor) so each backend applies identical semantics: prompt-suffix handling, resource-label defaults, the submit routing predicate, the bounded tool-call dispatch pool, and the submit-gate validation tail.
|
Package execshared holds behavior shared by the executor implementations (claudeexecutor, googleexecutor, openaiexecutor) so each backend applies identical semantics: prompt-suffix handling, resource-label defaults, the submit routing predicate, the bounded tool-call dispatch pool, and the submit-gate validation tail. |
|
executor/internal/telemetry
Package telemetry provides the shared GenAI metrics recorder used by the executor implementations (claudeexecutor, googleexecutor, openaiexecutor) so each backend emits identically-shaped metrics, differing only in the gen_ai.provider.name attribute.
|
Package telemetry provides the shared GenAI metrics recorder used by the executor implementations (claudeexecutor, googleexecutor, openaiexecutor) so each backend emits identically-shaped metrics, differing only in the gen_ai.provider.name attribute. |
|
executor/openaiexecutor
Package openaiexecutor provides a multi-turn conversation executor for OpenAI-compatible chat completion APIs, including Vertex AI's partner model endpoint.
|
Package openaiexecutor provides a multi-turn conversation executor for OpenAI-compatible chat completion APIs, including Vertex AI's partner model endpoint. |
|
executor/retry
Package retry provides exponential backoff retry logic for handling transient errors.
|
Package retry provides exponential backoff retry logic for handling transient errors. |
|
judge
Package judge provides LLM-based evaluation of model outputs using structured rubrics.
|
Package judge provides LLM-based evaluation of model outputs using structured rubrics. |
|
metaagent
Package metaagent provides a generic framework for building AI agents.
|
Package metaagent provides a generic framework for building AI agents. |
|
metrics
Package metrics provides OpenTelemetry metrics instrumentation for generative AI operations.
|
Package metrics provides OpenTelemetry metrics instrumentation for generative AI operations. |
|
promptbuilder
Package promptbuilder provides a safe, injection-resistant prompt construction library that leverages Go's standard encoding packages to automatically handle escaping and formatting.
|
Package promptbuilder provides a safe, injection-resistant prompt construction library that leverages Go's standard encoding packages to automatically handle escaping and formatting. |
|
rag
Package rag provides embedding generation, vector storage, and semantic retrieval for driftlessAF agents.
|
Package rag provides embedding generation, vector storage, and semantic retrieval for driftlessAF agents. |
|
result
Package result extracts a JSON result from free-form model text.
|
Package result extracts a JSON result from free-form model text. |
|
schema
Package schema provides JSON schema generation utilities for AI agent tool definitions.
|
Package schema provides JSON schema generation utilities for AI agent tool definitions. |
|
schema/schematest
Package schematest provides test helpers for comparing JSON schemas.
|
Package schematest provides test helpers for comparing JSON schemas. |
|
submitresult
Package submitresult provides tool definitions for AI agents to submit their final results.
|
Package submitresult provides tool definitions for AI agents to submit their final results. |
|
toolcall
Package toolcall defines composable tool providers for AI agents.
|
Package toolcall defines composable tool providers for AI agents. |
|
toolcall/callbacks
Package callbacks provides lightweight callback types for AI agent tool operations.
|
Package callbacks provides lightweight callback types for AI agent tool operations. |
|
toolcall/claudetool
Package claudetool converts unified toolcall.Tool definitions into Claude-compatible anthropic.ToolParam metadata for use with the [claudeexecutor].
|
Package claudetool converts unified toolcall.Tool definitions into Claude-compatible anthropic.ToolParam metadata for use with the [claudeexecutor]. |
|
toolcall/googletool
Package googletool converts unified toolcall.Tool definitions into Gemini-compatible genai.FunctionDeclaration metadata for use with the [googleexecutor].
|
Package googletool converts unified toolcall.Tool definitions into Gemini-compatible genai.FunctionDeclaration metadata for use with the [googleexecutor]. |
|
toolcall/openaistool
Package openaistool converts unified toolcall.Tool definitions into OpenAI-compatible openai.ChatCompletionToolParam metadata for use with the [openaiexecutor].
|
Package openaistool converts unified toolcall.Tool definitions into OpenAI-compatible openai.ChatCompletionToolParam metadata for use with the [openaiexecutor]. |
|
toolcall/params
Package params provides shared parameter extraction and error formatting utilities used by both Claude and Google tool implementations.
|
Package params provides shared parameter extraction and error formatting utilities used by both Claude and Google tool implementations. |
|
Package breaker provides a keyed circuit breaker for guarding reconcilers against remote dependencies returning transient errors.
|
Package breaker provides a keyed circuit breaker for guarding reconcilers against remote dependencies returning transient errors. |
|
internal
|
|
|
cloudrun
Package cloudrun resolves the identity of the running Cloud Run resource from its environment variables.
|
Package cloudrun resolves the identity of the running Cloud Run resource from its environment variables. |
|
reconcilers
|
|
|
apkreconciler
Package apkreconciler provides a workqueue-based reconciliation framework for APK packages.
|
Package apkreconciler provides a workqueue-based reconciliation framework for APK packages. |
|
apkreconciler/apkurl
Package apkurl provides utilities for parsing APK URL keys.
|
Package apkurl provides utilities for parsing APK URL keys. |
|
gcsstatusmanager
Package gcsstatusmanager provides a generic reconciliation status manager backed by Google Cloud Storage.
|
Package gcsstatusmanager provides a generic reconciliation status manager backed by Google Cloud Storage. |
|
githubreconciler
Package githubreconciler provides a workqueue-based reconciliation framework for GitHub pull requests.
|
Package githubreconciler provides a workqueue-based reconciliation framework for GitHub pull requests. |
|
githubreconciler/branchreconciler
Package branchreconciler provides a workqueue reconciler for iterative branch-based workflows without pull requests.
|
Package branchreconciler provides a workqueue reconciler for iterative branch-based workflows without pull requests. |
|
githubreconciler/changemanager
Package changemanager provides an abstraction for managing GitHub Pull Request lifecycle operations, similar to how the statusmanager handles GitHub Check Runs.
|
Package changemanager provides an abstraction for managing GitHub Pull Request lifecycle operations, similar to how the statusmanager handles GitHub Check Runs. |
|
githubreconciler/clonemanager
Package clonemanager provides pooled git clones tailored for reconciler style workloads.
|
Package clonemanager provides pooled git clones tailored for reconciler style workloads. |
|
githubreconciler/clonemanager/worktreefs
Package worktreefs implements io/fs.FS backed by callbacks.WorktreeCallbacks.
|
Package worktreefs implements io/fs.FS backed by callbacks.WorktreeCallbacks. |
|
githubreconciler/gitsign
Package gitsign provides a git commit signer backed by Sigstore keyless signing.
|
Package gitsign provides a git commit signer backed by Sigstore keyless signing. |
|
githubreconciler/graphqlclient
Package graphqlclient provides a thin wrapper around the GitHub GraphQL API client with Prometheus metrics instrumentation.
|
Package graphqlclient provides a thin wrapper around the GitHub GraphQL API client with Prometheus metrics instrumentation. |
|
githubreconciler/internal/template
Package template provides template execution and data embedding/extraction capabilities for GitHub reconcilers.
|
Package template provides template execution and data embedding/extraction capabilities for GitHub reconcilers. |
|
githubreconciler/issuemanager
Package issuemanager provides a reconciler-style abstraction for managing GitHub Issues based on desired state.
|
Package issuemanager provides a reconciler-style abstraction for managing GitHub Issues based on desired state. |
|
githubreconciler/metapathreconciler
Package metapathreconciler provides generic reconcilers for GitHub path handlers.
|
Package metapathreconciler provides generic reconcilers for GitHub path handlers. |
|
githubreconciler/metareconciler
Package metareconciler provides a generic reconciler for metaagent-based GitHub issue handlers.
|
Package metareconciler provides a generic reconciler for metaagent-based GitHub issue handlers. |
|
githubreconciler/statusmanager
Package statusmanager provides Kubernetes-style status management for GitHub reconcilers using GitHub Check Runs API.
|
Package statusmanager provides Kubernetes-style status management for GitHub reconcilers using GitHub Check Runs API. |
|
linearreconciler
Package linearreconciler provides a workqueue-based reconciliation framework for Linear issues.
|
Package linearreconciler provides a workqueue-based reconciliation framework for Linear issues. |
|
linearreconciler/metareconciler
Package metareconciler provides a generic reconciler that bridges Linear issues to GitHub PRs via an AI agent.
|
Package metareconciler provides a generic reconciler that bridges Linear issues to GitHub PRs via an AI agent. |
|
ocireconciler
Package ocireconciler provides a workqueue-based reconciliation framework for OCI image digests.
|
Package ocireconciler provides a workqueue-based reconciliation framework for OCI image digests. |
|
ocireconciler/statusmanager
Package statusmanager persists ocireconciler reconciliation state as OCI attestations.
|
Package statusmanager persists ocireconciler reconciliation state as OCI attestations. |
|
ocireconciler/statusmanager/testing
Package testing provides test helpers for the ocireconciler statusmanager.
|
Package testing provides test helpers for the ocireconciler statusmanager. |
|
resync
Package resync shards a time-bucketed resync across many cron firings, enqueuing only the slice of keys that belong in the current shard.
|
Package resync shards a time-bucketed resync across many cron firings, enqueuing only the slice of keys that belong in the current shard. |
|
statemachine
Package statemachine holds the reconciler state-machine vocabulary shared across metareconciler flavors: the Status/FailureMode value sets, the StateTransition record, the actor/trigger context plumbing, and the state-transition CloudEvent contract (StateTransitionEvent + Emitter).
|
Package statemachine holds the reconciler state-machine vocabulary shared across metareconciler flavors: the Status/FailureMode value sets, the StateTransition record, the actor/trigger context plumbing, and the state-transition CloudEvent contract (StateTransitionEvent + Emitter). |
|
transient
Package transient provides shared handling of transient upstream failures for reconcilers: Retry absorbs short blips in-process and marks errors it can't, and Is detects marked errors and temporary registry errors, so frameworks can requeue them instead of failing hard.
|
Package transient provides shared handling of transient upstream failures for reconcilers: Retry absorbs short blips in-process and marks errors it can't, and Is detects marked errors and temporary registry errors, so frameworks can requeue them instead of failing hard. |
|
Package workqueue contains an interface for a simple key workqueue abstraction.
|
Package workqueue contains an interface for a simple key workqueue abstraction. |
|
conformance
Package conformance provides a suite of conformance tests for workqueue implementations.
|
Package conformance provides a suite of conformance tests for workqueue implementations. |
|
dispatcher
Package dispatcher provides a workqueue dispatcher that dequeues keys and invokes a callback for each one.
|
Package dispatcher provides a workqueue dispatcher that dequeues keys and invokes a callback for each one. |
|
gcs
Package gcs provides a Google Cloud Storage-backed workqueue implementation.
|
Package gcs provides a Google Cloud Storage-backed workqueue implementation. |
|
hyperqueue
Package hyperqueue provides a sharded WorkqueueService implementation that consistently distributes keys across N backend workqueue services using consistent hashing.
|
Package hyperqueue provides a sharded WorkqueueService implementation that consistently distributes keys across N backend workqueue services using consistent hashing. |
|
inmem
Package inmem provides an in-memory workqueue implementation intended for testing.
|
Package inmem provides an in-memory workqueue implementation intended for testing. |
Click to show internal directories.
Click to hide internal directories.