pod

package
v0.1.2 Latest Latest
Warning

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

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

Documentation

Overview

init.go — scaffolding for new pod definitions.

`konareef pod init <name>` creates a minimal pod directory containing a pod.toml that validates against the v0.1 schema, a placeholder system prompt template, and an author-facing README. The generated tree is the fastest possible path from "I want to build a pod" to "I have something `konareef pod validate` accepts."

parse.go — typed-struct decoding for pod.toml documents.

Parse is intentionally permissive: it only catches TOML syntax errors. Missing required fields show up as zero values; conditional constraints (directive.task XOR template, wallet.reuse when strategy=reuse) are the schema's job and surface only via Validate or ParseAndValidate.

Callers that want both typed access AND schema-validation should use ParseAndValidate, which combines the two operations and gives a single place to handle each failure mode.

types.go — typed Go structs that mirror pod.toml v0.1.

These are the canonical client-side representation of a pod definition. Optional sections are pointers so callers can distinguish "absent" from "set to zero value" (matters for spawn-time decisions like whether to apply default budgets vs. explicit zeros).

The struct tags drive BurntSushi/toml decoding via Parse(). The schema validation happens separately in Validate() against the canonical JSON Schema; these types are not the schema's source of truth.

Package pod provides parsing and validation of konareef pod.toml files.

The canonical JSON Schema lives in the reef-core repo at priv/pod/spec_v0_1.schema.json; a vendored copy is embedded here so `konareef pod validate` runs offline without a reef-core round-trip. reef-core remains the authoritative parser at spawn time — local validation is a dev-time UX convenience, not a trust boundary.

Public surface:

  • Issue: a single validation problem with a structured path
  • Validate(podTOML): validate raw TOML bytes
  • ValidateFile(path): read and validate a file

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Init

func Init(opts InitOptions) ([]string, error)

Init scaffolds a new pod directory according to opts. Returns the list of files written (in deterministic order) on success, or a descriptive error if the name is invalid, the directory already exists, or any filesystem write fails.

The function is atomic-on-success in the sense that the destination directory is checked for existence up front: a partial scaffold can still leave files behind if a write fails midway, but the pre-flight check ensures Init never overwrites an existing pod tree.

func ParseAndValidate

func ParseAndValidate(podTOML []byte) (Spec, []Issue, error)

ParseAndValidate decodes podTOML into a Spec AND validates the original bytes against the embedded v0.1 schema. Returns the parsed Spec, any schema issues (empty when valid), and a non-nil error only when the TOML is malformed or the embedded schema fails to compile.

The parsed Spec is returned even when issues is non-empty — the caller can choose to surface a partial typed view alongside the issue list.

Typical usage in spawn-flow callers:

spec, issues, err := pod.ParseAndValidate(podTOML)
if err != nil {
    // malformed TOML or programmer error in the embedded schema
}
if len(issues) > 0 {
    // render issues to user; refuse to spawn
}
// spec is well-formed AND validated; proceed.

Types

type Budget

type Budget struct {
	MaxSats        int `toml:"max_sats,omitempty"`
	PerCallCapSats int `toml:"per_call_cap_sats,omitempty"`
	DailyCapSats   int `toml:"daily_cap_sats,omitempty"`
}

Budget is the [budget] table — sat-denominated spend caps.

type Context

type Context struct {
	Memory  []ContextMemory `toml:"memory,omitempty"`
	Skills  []ContextSkill  `toml:"skills,omitempty"`
	Tools   []ContextTool   `toml:"tools,omitempty"`
	Prompts []ContextPrompt `toml:"prompts,omitempty"`
}

Context is the context table — pre-loaded memory, skills, tools, and prompts injected before the directive fires.

type ContextMemory

type ContextMemory struct {
	Kind     string `toml:"kind"`
	Snapshot string `toml:"snapshot,omitempty"`
	Path     string `toml:"path,omitempty"`
	URL      string `toml:"url,omitempty"`
	Content  string `toml:"content,omitempty"`
}

ContextMemory is one [[context.memory]] entry.

type ContextPrompt

type ContextPrompt struct {
	Role string `toml:"role"`
	Path string `toml:"path"`
}

ContextPrompt is one [[context.prompts]] entry.

type ContextSkill

type ContextSkill struct {
	Source  string `toml:"source"`
	Version string `toml:"version,omitempty"`
}

ContextSkill is one [[context.skills]] entry.

type ContextTool

type ContextTool struct {
	Source string                 `toml:"source"`
	Config map[string]interface{} `toml:"config,omitempty"`
}

ContextTool is one [[context.tools]] entry.

type Deliverable

type Deliverable struct {
	Path        string `toml:"path"`
	Description string `toml:"description,omitempty"`
	Optional    bool   `toml:"optional,omitempty"`
}

Deliverable is one [[output.deliverables]] entry.

type Dependencies

type Dependencies struct {
	System  []string `toml:"system,omitempty"`
	Runtime []string `toml:"runtime,omitempty"`
	Secrets []string `toml:"secrets,omitempty"`
}

Dependencies is the [dependencies] table — system, runtime, and secret requirements resolved at spawn time. Secrets are *names only*; values come from reef-core's vault.

type Directive

type Directive struct {
	Task          string   `toml:"task,omitempty"`
	Template      string   `toml:"template,omitempty"`
	MaxIterations int      `toml:"max_iterations,omitempty"`
	ToolsAllowed  []string `toml:"tools_allowed,omitempty"`
	ToolsDenied   []string `toml:"tools_denied,omitempty"`
}

Directive is the [directive] table — the mission. Exactly one of Task or Template must be set; this is enforced by the schema.

type GPU

type GPU struct {
	Kind    string `toml:"kind"`
	Count   int    `toml:"count"`
	VRAMGiB int    `toml:"vram_gib"`
	Model   string `toml:"model,omitempty"`
}

GPU is the [hardware.gpu] sub-table.

type Hardware

type Hardware struct {
	CPUCores int    `toml:"cpu_cores,omitempty"`
	Memory   string `toml:"memory,omitempty"`
	Disk     string `toml:"disk,omitempty"`
	GPU      *GPU   `toml:"gpu,omitempty"`
}

Hardware is the [hardware] table — minimum resource requirements.

type Hooks

type Hooks struct {
	PreSpawn  string `toml:"pre_spawn,omitempty"`
	PostSpawn string `toml:"post_spawn,omitempty"`
	OnSuccess string `toml:"on_success,omitempty"`
	OnFailure string `toml:"on_failure,omitempty"`
}

Hooks is the [hooks] table — escape-hatch shell scripts at lifecycle points. Marketplace audits should flag any pod that uses these.

type Identity

type Identity struct {
	Name        string   `toml:"name"`
	Version     string   `toml:"version"`
	Authors     []string `toml:"authors,omitempty"`
	License     string   `toml:"license,omitempty"`
	Description string   `toml:"description,omitempty"`
	Homepage    string   `toml:"homepage,omitempty"`
	Tags        []string `toml:"tags,omitempty"`
	// LineageID is the 16-byte cross-session salt-lookup key, encoded
	// as a 32-character lowercase hex string. Set once at genesis by
	// `konareef pod init`. Type-C pods may ignore it; Type-D pods
	// require it to resolve lineage-scoped salt material.
	LineageID string `toml:"lineage_id,omitempty"`
}

Identity is the pod table — author-facing metadata.

type InitOptions

type InitOptions struct {
	// Name is the pod identifier — must match the v0.1 schema identifier
	// pattern. Required.
	Name string
	// Dir is the output directory. Defaults to "./<Name>" when empty.
	Dir string
	// Runtime is the runtime kind written into [runtime].kind. Defaults
	// to "lobster" when empty.
	Runtime string
	// Model is "<provider>/<name>" written into [model]. Defaults to
	// "anthropic/claude-sonnet-4-5" when empty. If no "/" is present
	// the entire string is treated as the model name and the provider
	// defaults to "anthropic".
	Model string
}

InitOptions controls pod scaffolding. All fields except Name have sensible defaults applied by Init when left empty.

type Input

type Input struct {
	Type        string `toml:"type"`
	Required    bool   `toml:"required,omitempty"`
	Description string `toml:"description,omitempty"`
}

Input is one [inputs.<name>] descriptor. v0.1 exposes only the fields callers need for prompt rendering and required-input enforcement; type- specific constraints (default, min, max, pattern, values) are validated at the schema layer and not surfaced through this struct yet.

type Inputs

type Inputs map[string]Input

Inputs is the [inputs] table — typed parameters callers pass at spawn. Maps the input name to its definition.

type Issue

type Issue struct {
	Path    string
	Message string
}

Issue describes a single validation problem.

Path is a dotted path into the pod.toml document with bracket notation for array indices, e.g. "context.skills[0].source". An empty Path means the issue applies to the whole document (e.g. a missing top-level key).

Message is a human-readable description of what went wrong.

func Validate

func Validate(podTOML []byte) ([]Issue, error)

Validate parses podTOML as a pod.toml document and checks the result against the embedded v0.1 schema.

It returns a slice of Issues (empty when the document is valid) and a non-nil error only when:

  • podTOML is not parseable as TOML, or
  • the embedded schema itself fails to compile (a build/programmer bug).

Schema-validation failures are returned as Issues, not as errors, so callers can render them as a list to the user rather than aborting.

func ValidateFile

func ValidateFile(path string) ([]Issue, error)

ValidateFile reads the file at path and validates it. The path argument is included in any I/O error returned for context.

func (Issue) String

func (issue Issue) String() string

String renders the issue in "path: message" form, or just "message" when no specific path is associated. Used for human-facing CLI output.

type Marketplace

type Marketplace struct {
	Listed      bool     `toml:"listed,omitempty"`
	PriceModel  string   `toml:"price_model,omitempty"`
	PriceSats   int      `toml:"price_sats,omitempty"`
	PreviewURL  string   `toml:"preview_url,omitempty"`
	Icon        string   `toml:"icon,omitempty"`
	Screenshots []string `toml:"screenshots,omitempty"`
	Categories  []string `toml:"categories,omitempty"`
}

Marketplace is the [marketplace] table — discovery + commerce metadata.

type Model

type Model struct {
	Provider     string                 `toml:"provider"`
	Name         string                 `toml:"name"`
	MaxTokens    int                    `toml:"max_tokens,omitempty"`
	Temperature  *float64               `toml:"temperature,omitempty"`
	ProviderOpts map[string]interface{} `toml:"provider_opts,omitempty"`
}

Model is the [model] table — selects the LLM driving the runtime. Temperature is a pointer because 0.0 is a valid explicit value distinct from "not set".

type Output

type Output struct {
	Format       string        `toml:"format,omitempty"`
	Success      []Predicate   `toml:"success,omitempty"`
	Failure      []Predicate   `toml:"failure,omitempty"`
	Deliverables []Deliverable `toml:"deliverables,omitempty"`
}

Output is the [output] table — success/failure predicates and deliverables. Used by reef-core to decide when a pod is "done".

type Predicate

type Predicate struct {
	Kind    string `toml:"kind"`
	Path    string `toml:"path,omitempty"`
	Count   int    `toml:"count,omitempty"`
	Pattern string `toml:"pattern,omitempty"`
	Value   int    `toml:"value,omitempty"`
	Tool    string `toml:"tool,omitempty"`
	Script  string `toml:"script,omitempty"`
}

Predicate is one [[output.success]] or [[output.failure]] entry. Kind discriminates which other fields are meaningful (e.g., kind="file_exists" requires Path; kind="min_words" requires Path+Count; kind="timeout_seconds" requires Value).

type Runtime

type Runtime struct {
	Kind    string `toml:"kind"`
	Version string `toml:"version,omitempty"`
}

Runtime is the runtime table — selects which harness to spawn.

type Spec

type Spec struct {
	PodSpecVersion string        `toml:"pod_spec_version"`
	Pod            Identity      `toml:"pod"`
	Runtime        Runtime       `toml:"runtime"`
	Model          *Model        `toml:"model,omitempty"`
	Hardware       *Hardware     `toml:"hardware,omitempty"`
	Dependencies   *Dependencies `toml:"dependencies,omitempty"`
	Context        *Context      `toml:"context,omitempty"`
	Inputs         Inputs        `toml:"inputs,omitempty"`
	Directive      *Directive    `toml:"directive,omitempty"`
	Output         *Output       `toml:"output,omitempty"`
	Budget         *Budget       `toml:"budget,omitempty"`
	Wallet         *Wallet       `toml:"wallet,omitempty"`
	Hooks          *Hooks        `toml:"hooks,omitempty"`
	Marketplace    *Marketplace  `toml:"marketplace,omitempty"`
}

Spec is the top-level pod.toml document.

func Parse

func Parse(podTOML []byte) (Spec, error)

Parse decodes podTOML into a Spec. Returns a non-nil error only when the input is not parseable as TOML; missing required fields and other schema violations are NOT caught here — use Validate for those.

func ParseFile

func ParseFile(path string) (Spec, error)

ParseFile reads a pod.toml file and parses it. The path argument is included in any I/O error returned for context.

type Wallet

type Wallet struct {
	Strategy string `toml:"strategy"`
	Reuse    string `toml:"reuse,omitempty"`
}

Wallet is the [wallet] table — wallet provisioning strategy. Reuse is required when Strategy = "reuse" (enforced by the schema).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL