Sample projects
Try command-line applications, reusable libraries, Rust integration, HTTP, Supervisors, and Low replacements. Each project includes nagi.toml and instructions. Standard HTTP and std.actor examples require Nagi 0.1.8 or later.
On this page
Examples for libraries and foundations
| Project | What it demonstrates |
|---|---|
| Pricing CLI | Validate input and call a shared calculation interface; switch between Nagi and Rust implementations |
| JSON report | Reuse the CLI's library and aggregate valid rows while handling invalid ones |
| Read JSON with Rust | Use serde_json and convert results to a Nagi class and Result |
| Rust async operation | Await a Tokio timer from Nagi |
| Custom HTTP foundation | Pass a synchronous Nagi function to Axum/Tokio and serve HTTP without opening a database |
| Standard HTTP and authentication | Handle headers, 401, route-specific errors, and typed shared state in Nagi |
| Supervisor and HTTP | Update actor state in order; map business errors and shutdown to HTTP responses |
| Low calculation kernel | Replace a High implementation with Low while keeping the application's calls |
| Modules and aliases | Distinguish same-named classes and use one type through a module name and a from alias |
| CLI with custom errors | Distinguish failures with an enum, preserve their causes, and choose display messages |
See libraries and Rust assets for the structure. Both pricing applications need shared/; obtain the whole sample directory.
Run a project
You need Rust/Cargo, Nagi, and a toolchain that can build applications on your OS. See setup and first run.
From the repository root:
nagic check --project test-nagi-code/library-examples/rust-json
nagic run --project test-nagi-code/library-examples/rust-json
Inside a project's directory, nagic check and nagic run use the same configuration. The pricing CLI waits for input; the HTTP foundation runs until Ctrl+C.
Selecting just a source file skips its neighboring nagi.toml. Use --project or a command without a source filename inside the directory to include its Rust, Low, and dependency settings.
Read complete applications
| Project | Contents |
|---|---|
| Task management | Browser UI, JSON API, and SQLite persistence |
| Result API | Invalid input, missing data, DB failures, and recovery |
| Inventory | Typed JSON input, CRUD, and aggregation |
| Stock JSON report | Read typed JSON from stdin and validate it with custom errors |
| Device settings API | Read SQLite NULL, boolean, float and BLOB columns; retain settings across restarts |
| Reservation worker | Handle duplicate bookings and capacity errors; restart one actor independently |
| Axum quote API | Serve HTTP with Rust/Axum; await a named Nagi async calculation returning Result |
| Rust bridge | CRC-32, serde_json, and async Rust functions |
| Fractal | Console output and distribution as an executable |
Each README explains its inputs, outputs, and limits. Rust integration examples cover the APIs and types listed there.
Verify the examples during development
With Python 3.12 or later, verify checks, native builds, output, and HTTP responses. Use a nagic built from the same source revision as the repository examples:
python scripts/verify_library_examples.py --compiler /path/to/nagic
python scripts/verify_application_examples.py --compiler /path/to/nagic
The script compares both pricing implementations, checks module and type aliases, custom errors, malformed JSON, and async errors, compares High/Low results, and verifies HTTP 400/404 responses, the body limit, and shutdown. The Supervisor sample also checks updates, state retained after business errors, a 204 shutdown response, and 503 after shutdown. It builds projects sequentially and shares the dependency cache.
On Unix it checks a clean exit after SIGINT. On Windows it terminates the process and checks that the listener closes; check console Ctrl+C manually using the HTTP sample's instructions.
verify_application_examples.py checks the applications. It independently checks and builds High applications from the original source and saved generated Low, and checks the handwritten Low order quote CLI directly. It checks input boundaries, existing-file protection, SQLite persistence, HTTP headers and errors, and Supervisor restarts, readiness and shutdown. Build warnings fail verification. Results and logs are written to build/application-example-verification/. CI runs it through build_examples.py.