spec

package module
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 31, 2026 License: Apache-2.0 Imports: 13 Imported by: 0

README

astro-spec

Parser and type definitions for the Astro AI agent specification (astropods.yml).

Go Reference Go Version

Spec Reference · Installation · Usage · The Spec · API

Overview

astro-spec is the single source of truth for how an agent's declarative configuration is parsed and validated across the Astro platform. It is consumed as a shared Go module by both:

  • astro-cli — builds, pushes, and registers agents, and
  • astro-server — deploys them to the cluster,

so the two always agree on the meaning of an astropods.yml. The package also emits a JSON Schema for editor autocomplete and validation.

📖 For the complete field-by-field specification, see the Astro Package Spec reference.

Installation

go get github.com/astropods/astro-spec

import spec "github.com/astropods/astro-spec"

Requires Go 1.24+.

Usage

Parse an astropods.yml from disk:

s, err := spec.ParseFile("astropods.yml")
if err != nil {
    log.Fatalf("invalid spec: %v", err)
}
fmt.Println(s.Name, "→", s.Agent.Image)
Function Input Validation
Parse(data []byte) in-memory bytes syntax only
ParseString(s string) in-memory string syntax only
ParseFile(path) file on disk syntax only
ParseSpec(path) file on disk required-field checks

The Spec

An AstroSpec describes one agent and its supporting components:

Field Purpose
spec Spec version — must be package/v1
name Unique agent name
meta Metadata such as visibility (public/private)
agent The main agent container (image or build)
models Model sidecar containers
knowledge Knowledge store containers
integrations Integration sidecar containers
providers Custom provider definitions
inputs User-supplied inputs injected into every container
ingestion Data ingestion pipelines
dev Local development overrides
Example
spec: package/v1
name: support-agent
meta:
  visibility: private

agent:
  image: ghcr.io/acme/support-agent:latest
  interfaces:
    frontend: true
    messaging: true

models:
  primary:
    provider: anthropic
  backup:
    provider: openai

knowledge:
  docs:
    provider: qdrant

integrations:
  github:
    provider: github

ingestion:
  docs-sync:
    container:
      image: acme/docs-ingest:latest
      environment:
        SOURCE_REPO: acme/handbook
    trigger:
      type: schedule

Components can reference one another with ${...} references (for example, an agent reading a knowledge store's connection URL).

API Surface

Area Functions
Parsing Parse, ParseString, ParseFile, ParseSpec
Validation ValidateName, ValidateVarName, SecretDefaultViolations, DeprecationWarnings
Env resolution ResolveEnvVars, AllCredentialKeys, AgentConnectionKeys, and related credential-key helpers
Providers LookupBuiltin, GetProvider, IsCloudModelProvider, IsGatewayModelProvider, CredentialKeys
JSON Schema Schema() — returns the embedded JSON Schema

JSON Schema

astropods.schema.json is generated by reflecting over the Go types. Regenerate it after changing any spec type:

go generate ./...
# equivalently:
go run ./cmd/generate-schema

Development

go test ./...

When you change a spec type, keep astropods.schema.json in sync by regenerating it (see JSON Schema).

Contributing

Contributions are welcome. Please open an issue or pull request. Before submitting, make sure the tests pass (go test ./...) and, if you touched any spec type, that the JSON Schema has been regenerated.

License

Part of the Astro AI platform. Licensed under the Apache License 2.0 — Copyright 2026 Postman Inc.

Documentation

Overview

Package spec provides shared type definitions for the Astro platform spec (astropods.yml). This package is used by both astro-cli and astro-server to ensure consistent parsing.

Index

Constants

View Source 
const AgentReadmeFilename = "AGENT.md"

AgentReadmeFilename is the canonical filename for an agent's README/card. Creation writes this exact name; readers match it case-insensitively so agent.md / Agent.md also resolve on case-sensitive sources.

View Source 
const DefaultAgentVolumeMount = "/data"

DefaultAgentVolumeMount is the mount path for the disk every agent gets by default. Setting agent.volume routes the agent through the StatefulSet + PVC path, so this makes persistent disk a guaranteed default. The messaging sidecar mounts the same volume under a subPath.

View Source 
const GatewayProviderName = "gateway"

GatewayProviderName is the reserved model provider that routes calls through the Astro AI Gateway. It is not a builtin container/cloud provider: it deploys no container and needs no user credentials — the platform injects ASTRO_GATEWAY_URL + ASTRO_GATEWAY_API_KEY at deploy time.

View Source 
const MaxAgentCardTags = 10

MaxAgentCardTags is the maximum number of tags allowed in an agent card.

View Source 
const MaxCapabilityLength = 100

MaxCapabilityLength is the maximum character length for a single capability entry.

View Source 
const MaxDescriptionLength = 200

MaxDescriptionLength is the maximum character length for an agent card description.

Variables

View Source 
var (

	// ReservedNames is the set of names that cannot be used for agents.
	// Enforced by both the CLI and the server.
	ReservedNames = map[string]bool{
		"astro":       true,
		"agent":       true,
		"model":       true,
		"integration": true,
	}
)

Functions

func AgentConnectionKeys 

func AgentConnectionKeys(s *AstroSpec, addrs map[string]ConnectionAddress) map[string]string

AgentConnectionKeys returns all env var keys that will be auto-injected into the agent for component connection wiring (§8.2 and §8.3). Keys are populated using the provided addrs map so that the caller controls whether values are concrete or deferred. Credential and input keys are NOT included — use CloudCredentialKeys for those.

func AgentKeysForComponent 

func AgentKeysForComponent(s *AstroSpec, section, entryName string) []string

AgentKeysForComponent returns the env var key names that one specific component contributes to the agent's environment, correctly handling duplicate-provider naming by evaluating within the full spec context.

section must be "models", "knowledge", or "integrations". entryName is the map key. Only connection keys are returned.

func AllAgentAutoEnvKeys 

func AllAgentAutoEnvKeys(s *AstroSpec) map[string]AgentEnvMeta

AllAgentAutoEnvKeys returns all env var keys automatically injected into the agent: connection wiring keys (§8.2/§8.3) and credential keys (§8.1, cloud + custom provider secrets). Inputs are not included as they are user-defined.

func AllCredentialKeys 

func AllCredentialKeys(s *AstroSpec) map[string]CredentialMeta

AllCredentialKeys returns all credential key names (cloud + custom provider secrets) that will be injected into the agent, with their metadata.

func CloudCredentialKeys 

func CloudCredentialKeys(s *AstroSpec) map[string]CredentialMeta

CloudCredentialKeys returns the env var key names and metadata for all cloud provider credentials derived from the spec (sections 8.1). The returned map is keyed by env var key (e.g. "ANTHROPIC_API_KEY").

This is the authoritative implementation of the duplicate-handling rule:

  • One entry for a provider → bare key {UPPER(provider)}_{suffix}.
  • Multiple entries for the same provider → qualified keys for all; the primary entry (name matches provider, else first alphabetically) also gets the bare key.
  • When entry name == provider name, the redundant qualified form is omitted.

func ComponentImageName 

func ComponentImageName(kind ComponentKind, agentName, name string) string

ComponentImageName returns the canonical image-name segment for a buildable component. For ComponentAgent the name is ignored and the agent name is returned directly; all other kinds use the {agent}-{kind}-{name} convention (e.g. "my-agent-knowledge-docs").

func CredentialKeys 

func CredentialKeys(provider string) []string

CredentialKeys returns the credential attribute names valid for ${knowledge.*.credentials.<attr>} references for the given provider. Derived from the provider registry's BindCredentials field.

func CredentialStorageKeyMap 

func CredentialStorageKeyMap(provider string) map[string]string

CredentialStorageKeyMap returns a map of storage key → reference attribute for a provider. Used at deploy time to map decrypted credential keys to reference attributes.

func CustomProviderCredentialKeys 

func CustomProviderCredentialKeys(s *AstroSpec) map[string]CredentialMeta

CustomProviderCredentialKeys returns the env var key names for all custom provider variables that are marked secret=true and are referenced by at least one component.

Keys follow §8.1: {UPPER(provider)}_{varName}, where varName is the variable suffix. Duplicate-entry handling mirrors §8.1: multiple entries referencing the same custom provider produce qualified keys; the primary entry also gets the bare key.

func DeprecatedMetaFields 

func DeprecatedMetaFields(specYAML []byte) []string

DeprecatedMetaFields checks raw spec YAML bytes for deprecated meta fields (description, tags) that have moved to AGENT.md frontmatter. Returns a list of human-readable deprecation messages for any found fields.

func DeprecationWarnings 

func DeprecationWarnings(s *AstroSpec) []string

DeprecationWarnings returns human-readable notices for deprecated spec usage. Callers (CLI validate/create) surface these without failing the parse.

func ExtractLegacyMeta 

func ExtractLegacyMeta(specMap map[string]any) (description string, tags []string)

ExtractLegacyMeta extracts deprecated description and tags from a raw spec map (as stored in spec_json). Used for backward-compatible display of existing agents that haven't migrated to AGENT.md.

func IsCloudIntegrationProvider 

func IsCloudIntegrationProvider(name string) bool

func IsCloudKnowledgeProvider 

func IsCloudKnowledgeProvider(name string) bool

func IsCloudModelProvider 

func IsCloudModelProvider(name string) bool

func IsGatewayModelProvider 

func IsGatewayModelProvider(name string) bool

IsGatewayModelProvider reports whether a model provider name refers to the Astro AI Gateway.

func IsManagedProvider 

func IsManagedProvider(section, name string) bool

func IsValidName 

func IsValidName(name string) bool

IsValidName reports whether name passes ValidateName.

func IsValidVarName 

func IsValidVarName(name string) bool

IsValidVarName reports whether name passes ValidateVarName.

func NormalizeTag 

func NormalizeTag(s string) string

NormalizeTag converts a tag string to a valid format: lowercase, spaces to hyphens, strip characters that aren't letters, numbers, or hyphens, collapse consecutive hyphens.

func RewriteMarkdownImages 

func RewriteMarkdownImages(md string, replace map[string]string) string

RewriteMarkdownImages returns md with every local image reference whose cleaned path is a key in replace rewritten to the mapped URL. References not present in replace (including all remote references) are left untouched.

func SanitizeDBName 

func SanitizeDBName(name string) string

SanitizeDBName converts an agent name into a valid Postgres database name. Same sanitization as SanitizeEnvName but returns lowercase (Postgres convention).

Examples: 

"memory-box" → "memory_box"
"my.agent"   → "my_agent"

func SanitizeEnvName 

func SanitizeEnvName(name string) string

SanitizeEnvName sanitizes an entry name and returns the uppercased form ready for use inside an env var key. Implements spec section 8.5.

Steps: lowercase → replace -, _ and . with _ → remove non-alphanumeric → collapse consecutive underscores → trim leading/trailing underscores → uppercase.

Examples: 

"my_model"  → "MY_MODEL"
"my.store"  → "MY_STORE"
"my-model"  → "MY_MODEL"
"llm"       → "LLM"
"local_llm" → "LOCAL_LLM"

func Schema 

func Schema() []byte

Schema returns the embedded JSON Schema for AstroSpec.

func SecretDefaultViolations 

func SecretDefaultViolations(s *AstroSpec) []string

SecretDefaultViolations returns the names of all secret inputs that still carry a non-empty default value. These must be stripped before registration to avoid storing credentials in the registry.

func StripSecretDefaults 

func StripSecretDefaults(specObj map[string]any)

StripSecretDefaults removes default values from all secret inputs across the raw YAML spec map so that credentials are not stored in the registry.

func TransformSpecForRegistry 

func TransformSpecForRegistry(specObj map[string]any, agentName string, imageRefFn func(imageName string) string) map[string]any

TransformSpecForRegistry rewrites a raw YAML spec map: it replaces every build block with the corresponding image reference and normalizes the name field. Only sections that have a build block are transformed; image-only sections are left unchanged.

imageRefFn is called with each component's canonical image name and must return the fully qualified image reference (e.g. "registry.io/acct/name:tag").

func ValidateName 

func ValidateName(name string) error

ValidateName checks whether name is a valid Astro agent name. Rules:

  • 4–63 characters
  • lowercase alphanumeric with hyphens only
  • must start with a lowercase letter
  • must end with alphanumeric
  • cannot be a reserved platform name (astro, agent, model, integration)

func ValidateVarName 

func ValidateVarName(name string) error

ValidateVarName checks whether name is a valid variable (secret) name. Rules: letters, digits, and underscores only; must start with a letter or underscore.

Types

type AgentCard 

type AgentCard struct {
	Description  string            `json:"description,omitempty" yaml:"description,omitempty"`
	Tags         []string          `json:"tags,omitempty" yaml:"tags,omitempty"`
	Authors      []AgentCardAuthor `json:"authors,omitempty" yaml:"authors,omitempty"`
	Repository   *AgentCardRepo    `json:"repository,omitempty" yaml:"repository,omitempty"`
	Capabilities []string          `json:"capabilities,omitempty" yaml:"capabilities,omitempty"`
	Integrations []string          `json:"-" yaml:"integrations,omitempty"`
}

AgentCard represents the structured frontmatter metadata from an AGENT.md file.

type AgentCardAuthor 

type AgentCardAuthor struct {
	Name    string `json:"name" yaml:"name"`
	Account string `json:"account,omitempty" yaml:"account,omitempty"`
}

AgentCardAuthor represents an author entry in the agent card frontmatter.

func (*AgentCardAuthor) UnmarshalYAML 

func (a *AgentCardAuthor) UnmarshalYAML(value *yaml.Node) error

UnmarshalYAML implements custom YAML unmarshaling for AgentCardAuthor, accepting both a plain string (used as Name) and an object form.

type AgentCardRepo 

type AgentCardRepo struct {
	Type      string `json:"type,omitempty" yaml:"type,omitempty"`
	URL       string `json:"url" yaml:"url"`
	Directory string `json:"directory,omitempty" yaml:"directory,omitempty"`
}

AgentCardRepo represents a source-code repository pointer. It can be specified as a shorthand string (e.g. "github:user/repo") or as an object with type, url, and optional directory.

func (*AgentCardRepo) UnmarshalYAML 

func (r *AgentCardRepo) UnmarshalYAML(value *yaml.Node) error

UnmarshalYAML implements custom YAML unmarshaling for AgentCardRepo, accepting both a shorthand string and an object form.

type AgentEnvMeta 

type AgentEnvMeta struct {
	Source   string // "connection" or "credential"
	Provider string // originating provider name (lowercase), e.g. "qdrant", "anthropic"
	Category string // "model", "knowledge", "integration", "provider"
	Optional bool   // credentials only
}

AgentEnvMeta describes one env var automatically injected into the agent.

type AstroSpec 

type AstroSpec struct {
	Spec         string                    `json:"spec" yaml:"spec" jsonschema:"description=Spec version. Must be package/v1"`
	Name         string                    `json:"name" yaml:"name" jsonschema:"description=Unique agent name"`
	Meta         Meta                      `json:"meta,omitempty" yaml:"meta,omitempty"`
	Agent        Container                 `json:"agent" yaml:"agent" jsonschema:"description=Main agent container"`
	Models       map[string]Model          `json:"models,omitempty" yaml:"models,omitempty" jsonschema:"description=Model sidecar containers"`
	Knowledge    map[string]Knowledge      `json:"knowledge,omitempty" yaml:"knowledge,omitempty" jsonschema:"description=Knowledge store containers"`
	Integrations map[string]Integration    `json:"integrations,omitempty" yaml:"integrations,omitempty" jsonschema:"description=Integration sidecar containers"`
	Providers    map[string]CustomProvider `json:"providers,omitempty" yaml:"providers,omitempty" jsonschema:"description=Custom provider definitions"`
	Inputs       map[string]Input          `json:"inputs,omitempty" yaml:"inputs,omitempty" jsonschema:"description=User-supplied inputs injected into every container"`
	Ingestion    map[string]Ingestion      `json:"ingestion,omitempty" yaml:"ingestion,omitempty" jsonschema:"description=Data ingestion pipelines"`
	Dev          *Dev                      `json:"dev,omitempty" yaml:"dev,omitempty" jsonschema:"description=Local development overrides"`
}

AstroSpec represents the complete Astro specification

func Parse 

func Parse(data []byte) (*AstroSpec, error)

Parse parses the spec content from bytes

func ParseFile 

func ParseFile(path string) (*AstroSpec, error)

ParseFile reads and parses an spec file from the given path

func ParseSpec 

func ParseSpec(path string) (*AstroSpec, error)

ParseSpec reads and parses an spec file with validation

func ParseString 

func ParseString(content string) (*AstroSpec, error)

ParseString parses the spec content from a string

func (*AstroSpec) UsesGateway 

func (s *AstroSpec) UsesGateway() bool

UsesGateway reports whether the agent uses the Astro AI Gateway — either via the deprecated agent.astro_ai_gateway boolean or a model with provider: gateway.

type BindCredentialDef 

type BindCredentialDef struct {
	Attr       string // reference attribute (e.g. "user", "password")
	StorageKey string // exact key in credentials store (e.g. "POSTGRES_USER")
}

BindCredentialDef maps a reference attribute name (used in ${knowledge.*.credentials.<attr>}) to the exact key stored in knowledge_store_credentials.

type BuildConfig 

type BuildConfig struct {
	Context    string            `json:"context" yaml:"context"`
	Dockerfile string            `json:"dockerfile" yaml:"dockerfile"`
	Target     string            `json:"target,omitempty" yaml:"target,omitempty"`
	Args       map[string]string `json:"args,omitempty" yaml:"args,omitempty"`
	Secrets    []BuildSecret     `json:"secrets,omitempty" yaml:"secrets,omitempty"`
}

type BuildSecret 

type BuildSecret struct {
	ID  string `json:"id" yaml:"id"`
	Env string `json:"env,omitempty" yaml:"env,omitempty"`
}

type BuiltinProvider 

type BuiltinProvider struct {
	Name    string // lowercase provider name (e.g. "anthropic", "qdrant")
	Section string // "models", "knowledge", or "integrations"
	Cloud   bool   // true → credentials only, no container deployed
	Managed bool   // true → server injects credentials from its own environment (user never provides them)

	// Cloud provider fields
	Credentials []CredentialSuffix

	// Self-hosted provider fields
	Image          string
	DefaultPort    int
	ExtraPorts     []PortDef
	MountPath      string
	EnvPrefix      string
	URLScheme      string
	HealthCheck    []string // exec health check; nil → use HealthPath
	HealthPath     string   // HTTP health check path
	DefaultEnv     map[string]string
	WritableRootFS bool     // true → skip readOnlyRootFilesystem (e.g. qdrant writes outside its data mount)
	ExtraEmptyDirs []string // extra paths that need writable emptyDir mounts (e.g. "/qdrant/snapshots")
	FsGroup        int64    // non-zero → pod runs as this uid/gid (overrides hardened default of 1000)
	InitSQL        string   // optional SQL run via /docker-entrypoint-initdb.d/ on first boot (postgres-compatible images only)

	// BindCredentials defines the credential schema for knowledge store bindings.
	// Each entry maps a reference attribute (e.g. "user") to its storage key (e.g. "USERNAME").
	// Used by ${knowledge.*.credentials.<attr>} reference validation and deploy-time resolution.
	BindCredentials []BindCredentialDef
}

BuiltinProvider is the single canonical type for every platform-known provider. All providers — cloud and self-hosted, across all sections — are declared once in the builtinProviders slice below. Everything else is derived from it.

func GetProvider 

func GetProvider(name string) BuiltinProvider

GetProvider returns self-hosted configuration for a knowledge provider. Unknown or cloud-only providers return a zero BuiltinProvider.

func LookupBuiltin 

func LookupBuiltin(section, name string) (BuiltinProvider, bool)

LookupBuiltin returns the BuiltinProvider for the given section and name. The second return value is false if the provider is not in the registry.

type Component 

type Component struct {
	Kind      ComponentKind // spec section this component belongs to
	Name      string        // map key within the spec section (empty for agent)
	ImageName string        // full image-name segment, e.g. "my-agent-integration-search"
	Build     *BuildConfig  // always non-nil (only buildable components are returned)
}

Component represents one buildable unit extracted from an AstroSpec. Only components with a build block are included.

func CollectComponents 

func CollectComponents(s *AstroSpec, agentName string) []Component

CollectComponents returns every component in the spec that has a build block. Components without a build block are omitted. The returned list uses canonical naming: {agent}-integration-{name} for integrations (matching the spec key), {agent}-model-{name} for models, etc.

func (Component) Suffix 

func (c Component) Suffix() string

Suffix returns a short identifier suitable for K8s job names. Examples: "agent", "model-llm", "integration-search".

type ComponentKind 

type ComponentKind string

ComponentKind identifies the spec section a buildable component belongs to. 

const (
	ComponentAgent       ComponentKind = "agent"
	ComponentModel       ComponentKind = "model"
	ComponentKnowledge   ComponentKind = "knowledge"
	ComponentIntegration ComponentKind = "integration"
	ComponentIngestion   ComponentKind = "ingestion"
)

type ConnectionAddress 

type ConnectionAddress struct {
	Host string
	Port string
	URL  string
}

ConnectionAddress holds the resolved connection details for a single component. Values may be concrete strings (docker DNS, k8s service DNS) or placeholder references (e.g. "${models.llm.host}") for deferred resolution.

type Container 

type Container struct {
	Image       string       `json:"image,omitempty" yaml:"image,omitempty"`
	Build       *BuildConfig `json:"build,omitempty" yaml:"build,omitempty"`
	Distributed bool         `` /* 134-byte string literal not displayed */
	Interfaces  *Interfaces  `` /* 126-byte string literal not displayed */
	Healthcheck *Healthcheck `json:"healthcheck,omitempty" yaml:"healthcheck,omitempty"`
	Inputs      []Input      `` /* 127-byte string literal not displayed */
	// AIGateway opts the agent into the Astro AI Gateway. DEPRECATED at the spec
	// level in favor of a model with `provider: gateway` — still honored (injects
	// ASTRO_GATEWAY_URL + ASTRO_GATEWAY_API_KEY, agent picks the model at call
	// time), but a gateway model entry also lets the deployer pick the model at
	// deploy time. The boolean and a gateway model entry are mutually exclusive.
	// (Not marked //Deprecated: so internal backward-compat reads don't trip SA1019.)
	AIGateway bool `` /* 226-byte string literal not displayed */
}

func (Container) HasFrontend 

func (c Container) HasFrontend() bool

HasFrontend reports whether the agent serves its own web frontend.

func (Container) HasMessaging 

func (c Container) HasMessaging() bool

HasMessaging reports whether the agent supports the messaging protocol. Returns true when interfaces is omitted (backward compat).

type ContainerConfig 

type ContainerConfig struct {
	Image       string            `json:"image,omitempty" yaml:"image,omitempty"`
	Build       *BuildConfig      `json:"build,omitempty" yaml:"build,omitempty"`
	GPU         *GPUConfig        `json:"gpu,omitempty" yaml:"gpu,omitempty"`
	Persistent  bool              `json:"-" yaml:"-"` // derived; set by ResolvedContainer
	Port        int               `json:"port,omitempty" yaml:"port,omitempty"`
	Volume      string            `` /* 131-byte string literal not displayed */
	Environment map[string]string `json:"environment,omitempty" yaml:"environment,omitempty"`
	Healthcheck *Healthcheck      `json:"healthcheck,omitempty" yaml:"healthcheck,omitempty"`
}

func (ContainerConfig) HasGPU 

func (c ContainerConfig) HasGPU() bool

HasGPU returns true when the container requires GPU resources.

type CredentialMeta 

type CredentialMeta struct {
	Provider    string
	Category    string // "model", "knowledge", "integration", "provider"
	Description string
	Optional    bool
}

CredentialMeta describes one required credential.

type CredentialSuffix 

type CredentialSuffix struct {
	Suffix      string
	Description string
	Optional    bool
}

CredentialSuffix describes one credential a cloud provider requires.

func GetCloudIntegrationCredentials 

func GetCloudIntegrationCredentials(name string) ([]CredentialSuffix, bool)

func GetCloudKnowledgeCredentials 

func GetCloudKnowledgeCredentials(name string) ([]CredentialSuffix, bool)

func GetCloudModelCredentials 

func GetCloudModelCredentials(name string) ([]CredentialSuffix, bool)

type CustomProvider 

type CustomProvider struct {
	Scope     []string       `json:"scope" yaml:"scope" jsonschema:"description=Sections that may reference this provider"`
	Variables []Input        `json:"variables" yaml:"variables" jsonschema:"description=Variables this provider requires from the user"`
	Config    map[string]any `json:"config,omitempty" yaml:"config,omitempty" jsonschema:"description=Provider-specific configuration"`
}

CustomProvider extends the platform's built-in provider registry. It declares the variables it requires so the platform can prompt at deploy time.

type Dev 

type Dev struct {
	Interfaces *DevInterfaces    `` /* 142-byte string literal not displayed */
	Schedules  map[string]string `json:"schedules,omitempty" yaml:"schedules,omitempty" jsonschema:"description=Cron schedules for ingestion jobs during dev"`
	Command    string            `` /* 135-byte string literal not displayed */
	Overrides  *DevOverrides     `json:"overrides,omitempty" yaml:"overrides,omitempty" jsonschema:"description=Image overrides for local dev services"`
}

Dev provides local development overrides read by `astro dev`.

func (*Dev) HasMessagingAdapters 

func (d *Dev) HasMessagingAdapters() bool

HasMessagingAdapters reports whether dev messaging adapters are configured.

func (*Dev) MessagingAdapters 

func (d *Dev) MessagingAdapters() []string

MessagingAdapters returns the dev messaging adapter names, or nil.

func (*Dev) MessagingLogLevel 

func (d *Dev) MessagingLogLevel() string

MessagingLogLevel returns the dev messaging sidecar log level, or empty when unset.

func (*Dev) SlackConfig 

func (d *Dev) SlackConfig() *SlackAdapterConfig

SlackConfig returns the Slack adapter configuration, or nil when not configured.

type DevFrontend 

type DevFrontend struct {
	Port int `` /* 148-byte string literal not displayed */
}

DevFrontend configures the agent's frontend for local development.

type DevInterfaces 

type DevInterfaces struct {
	Frontend  *DevFrontend  `json:"frontend,omitempty" yaml:"frontend,omitempty" jsonschema:"description=Local dev configuration for the agent frontend"`
	Messaging *DevMessaging `json:"messaging,omitempty" yaml:"messaging,omitempty" jsonschema:"description=Local dev configuration for messaging"`
}

DevInterfaces configures interfaces for local development. Supports both the legacy format (string array: [slack, web]) and the structured format ({frontend: {port: 3000}, messaging: {adapters: [slack]}}). The legacy format is treated as messaging.adapters.

func (DevInterfaces) JSONSchema 

func (DevInterfaces) JSONSchema() *jsonschema.Schema

JSONSchema returns a schema that accepts both the legacy string-array format (["web", "slack"]) and the structured object format ({frontend: ..., messaging: ...}).

func (*DevInterfaces) UnmarshalJSON 

func (d *DevInterfaces) UnmarshalJSON(data []byte) error

UnmarshalJSON supports the legacy string-array format for backward compatibility. This mirrors UnmarshalYAML so that specs stored as JSON (e.g. in the agent index) can be deserialized back into AstroSpec correctly.

func (*DevInterfaces) UnmarshalYAML 

func (d *DevInterfaces) UnmarshalYAML(unmarshal func(interface{}) error) error

UnmarshalYAML supports the legacy string-array format for backward compatibility.

type DevMessaging 

type DevMessaging struct {
	Adapters []string            `` /* 126-byte string literal not displayed */
	Slack    *SlackAdapterConfig `json:"slack,omitempty" yaml:"slack,omitempty" jsonschema:"description=Slack-specific adapter configuration"`
	LogLevel string              `` /* 159-byte string literal not displayed */
}

DevMessaging configures the messaging sidecar for local development.

type DevOverrides 

type DevOverrides struct {
	MessagingImage  string `` /* 127-byte string literal not displayed */
	PlaygroundImage string `json:"playgroundImage,omitempty" yaml:"playgroundImage,omitempty" jsonschema:"description=Custom image for the playground UI"`
}

DevOverrides allows overriding default images for local dev services.

type EnvResult 

type EnvResult struct {
	Agent        map[string]string
	Models       map[string]map[string]string
	Knowledge    map[string]map[string]string
	Integrations map[string]map[string]string
	Ingestion    map[string]map[string]string
}

EnvResult holds the computed env var maps for every container.

func ResolveEnvVars 

func ResolveEnvVars(s *AstroSpec, addrs map[string]ConnectionAddress, credentials, inputValues map[string]string) EnvResult

ResolveEnvVars computes the complete env var injection for all containers in a spec.

Parameters:

  • addrs: maps "models.{name}", "knowledge.{name}", "tools.{name}" to connection details. Values may be concrete strings or deferred placeholders.
  • credentials: maps credential key → value (cloud + custom-provider secrets).
  • inputValues: maps input name → user-supplied value (falls back to Input.Default).

Returns an EnvResult with one map per container.

type GPUConfig 

type GPUConfig struct {
	VRAM    string `json:"vram,omitempty" yaml:"vram,omitempty" jsonschema:"description=GPU memory required (e.g. 24Gi)"`
	Runtime string `json:"runtime,omitempty" yaml:"runtime,omitempty" jsonschema:"description=GPU runtime,enum=cuda,enum=rocm"`
}

GPUConfig is a scheduling hint declaring that a container needs GPU resources. VRAM (e.g. "24Gi") tells the server how much GPU memory the workload needs. Runtime is "cuda" (default) or "rocm".

type Healthcheck 

type Healthcheck struct {
	Test     []string `json:"test,omitempty" yaml:"test,omitempty"`         // Custom health check command (e.g., ["CMD", "redis-cli", "ping"])
	Path     string   `json:"path,omitempty" yaml:"path,omitempty"`         // HTTP path for health check (auto-generates test command)
	Interval string   `json:"interval,omitempty" yaml:"interval,omitempty"` // How often to check (default: 10s)
	Timeout  string   `json:"timeout,omitempty" yaml:"timeout,omitempty"`   // Time to wait for response (default: 5s)
	Retries  int      `json:"retries,omitempty" yaml:"retries,omitempty"`   // Number of retries before unhealthy (default: 3)
}

type Ingestion 

type Ingestion struct {
	Container ContainerConfig  `json:"container" yaml:"container"`
	Trigger   IngestionTrigger `json:"trigger" yaml:"trigger"`
	Inputs    []Input          `` /* 131-byte string literal not displayed */
}

Ingestion represents a data ingestion job — a container that runs on a trigger.

type IngestionTrigger 

type IngestionTrigger struct {
	Type string `json:"type" yaml:"type" jsonschema:"description=When the ingestion runs,enum=schedule,enum=manual,enum=startup,enum=webhook"`
}

type Input 

type Input struct {
	Name        string   `json:"name" yaml:"name" jsonschema:"description=Env var key injected into the target container"`
	Datatype    string   `` /* 127-byte string literal not displayed */
	Secret      bool     `json:"secret,omitempty" yaml:"secret,omitempty" jsonschema:"description=If true, stored securely and never logged"`
	Description string   `json:"description,omitempty" yaml:"description,omitempty"`
	DisplayAs   string   `` /* 141-byte string literal not displayed */
	Options     []string `json:"options,omitempty" yaml:"options,omitempty" jsonschema:"description=Allowed values; required when display-as is select"`
	Default     string   `json:"default,omitempty" yaml:"default,omitempty"`
	Optional    bool     `json:"optional,omitempty" yaml:"optional,omitempty" jsonschema:"description=If true, may be omitted at deploy time"`
}

Input declares a user-supplied value prompted at deploy time and injected as an env var. The name is used directly as the env var key in the target container.

type Integration 

type Integration struct {
	Provider  string           `` /* 132-byte string literal not displayed */
	Container *ContainerConfig `json:"container,omitempty" yaml:"container,omitempty"`
	Inputs    []Input          `` /* 133-byte string literal not displayed */
}

func (Integration) DeploysContainer 

func (t Integration) DeploysContainer(customProviders map[string]CustomProvider) bool

DeploysContainer reports whether this tool entry deploys a sidecar container.

func (Integration) IsProviderMode 

func (t Integration) IsProviderMode() bool

IsProviderMode returns true when the integration entry uses a cloud provider.

type Interfaces 

type Interfaces struct {
	Frontend  bool `json:"frontend,omitempty" yaml:"frontend,omitempty" jsonschema:"description=Agent serves its own web interface on port 80"`
	Messaging bool `json:"messaging,omitempty" yaml:"messaging,omitempty" jsonschema:"description=Agent supports the messaging protocol"`
}

Interfaces declares agent interface capabilities. When nil (omitted), the platform defaults to messaging enabled. When present, both fields default to false.

type Knowledge 

type Knowledge struct {
	Provider  string           `json:"provider,omitempty" yaml:"provider,omitempty"`
	Container *ContainerConfig `json:"container,omitempty" yaml:"container,omitempty"`
	Inputs    []Input          `` /* 131-byte string literal not displayed */
}

func (Knowledge) DeploysContainer 

func (k Knowledge) DeploysContainer(customProviders map[string]CustomProvider) bool

DeploysContainer reports whether this knowledge entry deploys a sidecar container.

func (Knowledge) IsProviderMode 

func (k Knowledge) IsProviderMode() bool

IsProviderMode returns true when the knowledge entry uses a platform-managed provider.

func (Knowledge) ResolvedContainer 

func (k Knowledge) ResolvedContainer() ContainerConfig

ResolvedContainer returns the effective ContainerConfig — either built from the provider registry (provider mode) or passed through from the user's container block (container mode). Persistent is derived from Volume so the invariant Persistent ⇔ Volume != "" holds in both modes.

type KnownIntegration 

type KnownIntegration struct {
	ID      string   `json:"id"`
	Name    string   `json:"name"`
	Aliases []string `json:"aliases,omitempty"`
}

KnownIntegration represents an entry in the known integrations registry.

func KnownIntegrations 

func KnownIntegrations() []KnownIntegration

KnownIntegrations returns the full list of known integrations from the embedded registry.

func ResolveIntegration 

func ResolveIntegration(name string) *KnownIntegration

ResolveIntegration matches an integration string against the known integrations registry. Returns nil if no match is found (unknown integration).

Matching rules:

  1. Normalize input: lowercase, trim whitespace.
  2. Look up in the precomputed map (covers id, name, and alias matches).
  3. No match → return nil.

type MarkdownImage 

type MarkdownImage struct {
	// Path is the cleaned, repo-relative path used both as the file to load and
	// as the key for rewriting. Percent-decoding, query/fragment stripping, and
	// lexical cleaning are already applied (e.g. "./docs/x.png?v=1" → "docs/x.png").
	Path string
}

MarkdownImage is a local (repo-relative) image reference discovered in an AGENT.md document.

func ExtractMarkdownImages 

func ExtractMarkdownImages(md string) []MarkdownImage

ExtractMarkdownImages returns the deduplicated, first-seen-ordered set of local image references in md. Both Markdown image syntax and HTML <img> tags are scanned. Remote (scheme:// or //host), data:, anchor-only, root-absolute (/foo), and parent-escaping (../) references are skipped.

type Meta 

type Meta struct {
	Visibility string `` /* 141-byte string literal not displayed */
}

type Model 

type Model struct {
	Provider  string           `` /* 145-byte string literal not displayed */
	Models    []string         `json:"models,omitempty" yaml:"models,omitempty" jsonschema:"description=Model identifiers to make available"`
	Model     string           `` /* 127-byte string literal not displayed */
	Container *ContainerConfig `` /* 128-byte string literal not displayed */
	Inputs    []Input          `` /* 127-byte string literal not displayed */
}

func (Model) DeploysContainer 

func (m Model) DeploysContainer(customProviders map[string]CustomProvider) bool

DeploysContainer reports whether this model entry deploys a sidecar container. Only container-mode models deploy a sidecar; provider-mode models are cloud (credentials only) or custom (no container).

func (Model) IsGateway 

func (m Model) IsGateway() bool

IsGateway reports whether this model routes through the Astro AI Gateway.

func (Model) IsProviderMode 

func (m Model) IsProviderMode() bool

IsProviderMode returns true when the model entry uses a platform-managed provider.

func (Model) ResolvedContainer 

func (m Model) ResolvedContainer() ContainerConfig

ResolvedContainer returns the effective ContainerConfig for a container-mode model. Provider-mode models never deploy a container, so this returns a zero value for them.

func (Model) ResolvedModels 

func (m Model) ResolvedModels() []string

ResolvedModels returns the effective list of model identifiers, merging the deprecated Model field into Models.

type ParsedAgentCard 

type ParsedAgentCard struct {
	AgentCard
	Body                 string                `json:"body"`
	ResolvedIntegrations []ResolvedIntegration `json:"integrations,omitempty"`
	// Warnings describe fields that were invalid and dropped/truncated. Display-only;
	// not stored or serialized to clients.
	Warnings []string `json:"-"`
}

ParsedAgentCard is the result of parsing an AGENT.md file.

func ParseAgentCard 

func ParseAgentCard(content string) *ParsedAgentCard

ParseAgentCard parses raw AGENT.md content into structured metadata and a markdown body. It extracts YAML frontmatter (delimited by --- lines) and returns the remaining content as body.

Parsing is best-effort: any field that fails to validate is dropped and recorded in result.Warnings. The function never returns a nil result.

func ParseAgentCardFile 

func ParseAgentCardFile(path string) (*ParsedAgentCard, error)

ParseAgentCardFile reads and parses an AGENT.md file from the given path. If the file does not exist, it returns an empty ParsedAgentCard without error. Parsing the file contents is best-effort; see ParseAgentCard.

type PortDef 

type PortDef struct {
	Name string
	Port int
}

PortDef defines a named port.

type Provider 

type Provider = BuiltinProvider

Provider holds self-hosted container configuration. Returned by GetProvider for backward compatibility with existing callers.

type ResolvedIntegration 

type ResolvedIntegration struct {
	ID    string `json:"id"`
	Name  string `json:"name"`
	Known bool   `json:"known"`
}

ResolvedIntegration is an integration entry resolved against the known registry.

func MergeResolvedIntegrations 

func MergeResolvedIntegrations(existing []ResolvedIntegration, additional []string) []ResolvedIntegration

MergeResolvedIntegrations resolves additional integration strings and merges them into existing resolved integrations, deduplicating by ID.

type SlackAdapterConfig 

type SlackAdapterConfig struct {
	ActionableReactions []string       `` /* 196-byte string literal not displayed */
	AllowedChannelIDs   []string       `` /* 184-byte string literal not displayed */
	AllowedUserIDs      []string       `` /* 172-byte string literal not displayed */
	ObserveChannelIDs   []string       `` /* 190-byte string literal not displayed */
	SocketMode          *bool          `` /* 140-byte string literal not displayed */
	AutoThread          *bool          `` /* 130-byte string literal not displayed */
	Extra               map[string]any `json:"-" yaml:",inline" jsonschema:"-"`
}

SlackAdapterConfig holds behavioral settings for the Slack messaging adapter. Shared between the dev (compose builder) and deployment (template generator) paths. Serialized as JSON into the SLACK_CONFIG env var for the messaging sidecar.

Extra captures any keys present under dev.interfaces.messaging.slack that aren't named fields above, so new messaging-sidecar options can be passed through without changes here.

func (SlackAdapterConfig) MarshalJSON 

func (s SlackAdapterConfig) MarshalJSON() ([]byte, error)

MarshalJSON flattens Extra into the top-level JSON object alongside the named fields. Named fields win on key conflict.

func (*SlackAdapterConfig) UnmarshalJSON 

func (s *SlackAdapterConfig) UnmarshalJSON(data []byte) error

UnmarshalJSON pulls out the named fields and routes any remaining keys into Extra so they round-trip back through MarshalJSON unchanged.

Source Files

View all Source files

Directories

Path Synopsis
cmd
generate-schema command
Command generate-schema reflects spec.AstroSpec into a JSON Schema and writes it to package.schema.json in the package root.
 Command generate-schema reflects spec.AstroSpec into a JSON Schema and writes it to package.schema.json in the package root.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.