Skip to content

getting-started-sdk.md

Latest commit

 

History

History
229 lines (166 loc) · 5.84 KB

getting-started-sdk.md

File metadata and controls

229 lines (166 loc) · 5.84 KB
Authority CANONICAL
Version v1
Last Updated 2026-03-26
Owner Sebastian (Architect)
Scope Getting started workflow for SDK-first Ergo projects
Change Rule Tracks implementation

Getting Started with Ergo SDK

This guide walks through the current v1 Ergo project workflow.

Use this when you want to create a new Ergo application, run the sample project, and understand where to put your code and authored assets.

1. Scaffold a Project

From inside an Ergo checkout, create a new Rust crate plus Ergo project layout:

ergo init my-project

ergo init generates:

  • README.md
  • Cargo.toml
  • ergo.toml
  • src/main.rs
  • src/implementations/
  • graphs/
  • clusters/
  • adapters/
  • channels/ingress/
  • channels/egress/
  • egress/
  • fixtures/
  • captures/

The generated Cargo.toml currently points at a local ergo-sdk-rust checkout.

  • Inside the Ergo repository, ergo init wires that dependency automatically with a relative path.
  • Outside the repository, pass --sdk-path <path-to-ergo-sdk-rust> until the SDK is published outside the repo.

2. Run the Sample Project

The scaffolded crate is runnable immediately:

cd my-project
cargo run

The generated README.md is the first stop after scaffolding. It summarizes the project layout, available profiles, and the first files to edit.

The scaffolded run command also installs a Ctrl-C handler through StopHandle.

This default path runs the historical profile from ergo.toml:

  • graph: graphs/strategy.yaml
  • cluster search path: implicit clusters/
  • adapter: adapters/sample.yaml
  • ingress source: fixtures/historical.jsonl
  • egress config: egress/live.toml
  • capture output: captures/historical.capture.json

The sample run proves the full SDK path:

  • in-process custom primitive registration
  • project/profile resolution
  • cluster loading
  • adapter-bound execution
  • external intent dispatch
  • capture output

Current sample boundary programs are Python 3 examples:

  • channels/ingress/live_feed.py
  • channels/egress/sample_outbox.py

Make sure python3 is available on your machine before using the scaffolded historical or live profiles, or the scaffolded doctor command.

For user-authored long-running process-ingress profiles, Ctrl-C requests a graceful host stop instead of hard-killing the process. That lets the run finalize cleanly and still write its capture artifact. The scaffolded live sample itself is short-lived: it emits one event and an explicit end frame, then exits on its own.

Existing apps only get that behavior when they wire StopHandle and call run_profile_with_stop(...). run_profile() remains the raw blocking API when you do not want the scaffolded stop-aware path.

3. Validate and Replay

Validate every named profile in the project:

cargo run -- validate

List the named profiles in the scaffolded project:

cargo run -- profiles

Run the scaffold health check:

cargo run -- doctor

Replay the generated historical capture:

cargo run -- replay historical captures/historical.capture.json

The scaffolded main.rs is intentionally small. It shows how to:

  • build Ergo from the project root
  • register custom primitives
  • run one named profile
  • list available profiles
  • doctor the scaffolded project
  • validate the project
  • replay a capture

4. Where To Edit Things

Custom primitives

Edit:

  • src/implementations/sources.rs
  • src/implementations/actions.rs

The sample project includes:

  • a custom Source primitive that emits a string message
  • a custom Action primitive that emits an external intent plus a mirror write

Add your own Source, Compute, Trigger, and Action implementations here, then register them in src/main.rs.

Graphs and clusters

Edit:

  • graphs/strategy.yaml
  • clusters/sample_message.yaml

The sample graph already references the sample cluster, so clusters are part of the normal project flow from day one.

Adapter contract

Edit:

  • adapters/sample.yaml

This is where event kinds, context keys, accepted effect kinds, and capture fields are declared.

Boundary channels

Edit:

  • channels/ingress/live_feed.py
  • channels/egress/sample_outbox.py
  • egress/live.toml

The sample project includes both ingress and egress channel programs. The historical profile uses fixture ingress. The live profile uses the process ingress script plus the same egress routing config.

5. Manifest Split

Keep the two top-level manifests separate:

  • Cargo.toml Rust build and dependency configuration
  • ergo.toml Ergo project profiles and authored-asset wiring

ergo.toml is the project authority for:

  • graph path
  • adapter path
  • exactly one ingress source per profile
  • optional egress config path
  • capture output

6. Current v1 Limits

  • One ingress channel per profile.
  • The SDK handle is same-thread reusable, including validation, run, replay, and profile-stepping operations.
  • runner_for_profile(...) is a low-level manual stepping surface over resolved profile assets. It still requires a normal profile with one declared ingress source, but it does not launch that ingress.
  • runner_for_profile(...) honors graph, cluster paths, adapter, and egress, but it ignores ingress, max_duration, and max_events while stepping manually.
  • finish() returns a CaptureBundle and does not auto-write capture_output; finish_and_write_capture() is the explicit path that applies capture_output / pretty_capture.
  • CLI remains supporting tooling. The production surface is the Rust crate you scaffold and run with Cargo.

7. Read Next