This tutorial shows how to migrate existing Geppetto integrations from the old layer/parameter APIs to the new section/value facade APIs, with no backward compatibility shims. It is intended for maintainers who want to complete a hard-cut migration and remove deprecated symbol usage.

What changes conceptually:

• layers becomes sections for schema definitions.
• parameters becomes values for parsed runtime data.
• helper APIs that accepted ParsedLayers now accept ParsedValues.

Scope and Preconditions

Use this guide when your code currently imports old Geppetto symbols such as:

• github.com/go-go-golems/geppetto/pkg/layers
• factory.NewEngineFromParsedLayers(...)
• settings.NewStepSettingsFromParsedLayers(...)
• stepSettings.UpdateFromParsedLayers(...)
• embeddings.NewSettingsFactoryFromParsedLayers(...)

Before starting:

• update to a Geppetto version that exports pkg/sections and ...FromParsedValues APIs.
• ensure your Glazed usage is already on schema/values in command pipelines.

Symbol Mapping

Use this mapping as the canonical replacement list.

Import Migration

Before:

import geppettolayers "github.com/go-go-golems/geppetto/pkg/layers"

After:

import geppettosections "github.com/go-go-golems/geppetto/pkg/sections"

Command Schema Wiring

Before:

geppettoLayers, err := geppettolayers.CreateGeppettoLayers()
if err != nil { return err }

desc := cmds.NewCommandDescription(
    "run",
    cmds.WithLayers(geppettoLayers...),
)

After:

geppettoSections, err := geppettosections.CreateGeppettoSections()
if err != nil { return err }

desc := cmds.NewCommandDescription(
    "run",
    cmds.WithSections(geppettoSections...),
)

Parsed Data and Engine Factory

Before:

eng, err := factory.NewEngineFromParsedLayers(parsedLayers)
if err != nil { return err }

After:

eng, err := factory.NewEngineFromParsedValues(parsedValues)
if err != nil { return err }

If you build settings first:

Before:

stepSettings, err := settings.NewStepSettingsFromParsedLayers(parsedLayers)
if err != nil { return err }

After:

stepSettings, err := settings.NewStepSettingsFromParsedValues(parsedValues)
if err != nil { return err }

Before:

if err := stepSettings.UpdateFromParsedLayers(parsedLayers); err != nil {
    return err
}

After:

if err := stepSettings.UpdateFromParsedValues(parsedValues); err != nil {
    return err
}

Embeddings Factory Migration

Before:

factory, err := embeddings.NewSettingsFactoryFromParsedLayers(parsedLayers)
if err != nil { return err }

After:

factory, err := embeddings.NewSettingsFactoryFromParsedValues(parsedValues)
if err != nil { return err }

Provider Section Constructors

When you directly assemble sections, switch constructor names:

chat, _ := settings.NewChatValueSection()
client, _ := settings.NewClientValueSection()
openaiSection, _ := openai.NewValueSection()
claudeSection, _ := claude.NewValueSection()
geminiSection, _ := gemini.NewValueSection()
ollamaSection, _ := ollama.NewValueSection()
embeddingsSection, _ := config.NewEmbeddingsValueSection()

Validation Checklist

After replacement, verify all of the following:

• no imports of geppetto/pkg/layers.
• no calls to *FromParsedLayers.
• no calls to *ParameterLayer constructors for Geppetto settings.
• project builds and tests with current Geppetto and Glazed.
• go mod tidy removes stale module edges introduced by deleted old symbols.

Useful checks:

rg -n "pkg/layers|FromParsedLayers|ParameterLayer" .
go test ./...
make lint

Troubleshooting

See Also

• ../tutorials/01-streaming-inference-with-tools.md
• ../topics/06-inference-engines.md
• ../topics/06-embeddings.md