ari-core 0.1.0b1

Core workflow engine and OSS runtime for Ari

ari-core

AI workflows for engineer that actually work.

Quick links: Getting Started · Core Concepts · API Cheatsheet

What is ari-core?

ari-core is the open workflow framework layer of Ari.

It provides:

• workflow primitives (Step, Segment, DataModel)
• interaction primitives (prompt, choice, confirm, ui)
• local workflow orchestration/runtime for execution

It is designed for (citizen) developers in civil engineering who want to build practical AI workflows.

Why use it?

• Built for real workflows, not demos
  Structured Step/Segment execution for predictable flow.
• Low friction for (citizen) developers
  Simple primitives to author workflows without heavy framework overhead.
• Human-in-the-loop by default
  prompt, choice, confirm, and ui make guided interactions easy.
• Local-first execution
  Run and iterate quickly on your own machine.
• Domain fit for civil engineering teams
  Good for repeatable process support, review flows, and decision guidance.
• Composable and extensible
  Add new steps/components as workflow needs grow.

Installation

Requirements

• Python 3.12+
• uv (recommended)

Install

uv add ari-core

Verify

python -c "import ari_core; print('ari-core installed')"

Quick Start (2-minute example)

Create a new workflow project:

uv run ari new my-workflow
cd my-workflow

Run locally:

uv run main.py

What happens:

• You select a segment
• Steps run in order
• Prompts/UI appear as defined by the workflow

Next:

• Step Authoring
• Segment Guide

Core Concepts

ari-core workflows are built from a few core primitives:

• DataModel: typed value object passed between steps
• Step: unit of workflow logic (execute(ctx))
• Segment: user-selectable flow of ordered step classes
• SegmentRegistry: registry of available segments
• State tables:
  • Table.WORKFLOW for per-run/session data
  • Table.PROJECT for persistent project-level data

Execution lifecycle:

1. User selects a segment
2. Steps run in order
3. Each step loads declared requires, executes, then persists declared produces
4. User can select another segment or finish

Rule of thumb:

• Default to Table.WORKFLOW
• Use Table.PROJECT only when data must persist across runs

Interaction & UI primitives

Use Ari interaction primitives inside Step.execute(...):

• prompt(message) for free-form input
• choice(message, choices) for selecting from known options
• confirm(message, default=False) for yes/no decisions
• ui(component) for richer browser-rendered interactions

Notes:

• Keep interaction logic close to the step that owns the decision
• ui(component) requires component.render_html() -> str
• Return values from browser UI should be posted back to the runtime

For building custom UI components, see UI Components.

Running locally

Run your workflow project locally:

uv run main.py

Local runtime behavior:

• Terminal interactions for prompt(...), choice(...), and confirm(...)
• Browser-based rendering for ui(...) components

This is the default mode for fast development and iteration.

Web based version

Besides local execution, you can publish your workflow to a hosted web demo so users can run it directly in the browser.

To request access to the demo environment, go to: https://brugnaarai.nl

Publish flow

From your workflow project directory:

uv run ari demo-push

This demo web environment is designed for easy sharing with colleagues, making workflow usage and distribution straightforward.

CLI usage

Common commands:

uv run ari new <project-name>
uv run ari demo-push

Use new to scaffold a workflow project and demo-push to publish it to the web demo environment.

Documentation map

Detailed guides are available in ari_core/docs/:

• Core Concepts
• API Cheatsheet
• Getting Started
• Step Authoring
• Step Contracts and Errors
• UI Components
• Segment Guide
• Database Guide
• Publish to Demo
• Issues and Questions

Contributing / development

Contributions are welcome — bug fixes, improvements, docs updates, and new workflow capabilities.

Before you start

• Check existing guidance in Issues and Questions
• If you are unsure about direction, open an issue first to discuss approach

Local development

cd packages/ari-core
uv sync

Run tests

uv run pytest

Submitting a PR

• Keep PRs focused and small where possible
• Include/update tests when behavior changes
• Update docs when user-facing behavior changes
• Use clear PR titles and descriptions (what changed, why, and how to test)
• Request @tom as reviewer before merging

Raising issues

If you hit a bug, unclear behavior, or documentation gap, open an issue and follow the structure in:

• Issues and Questions

Versioning & stability notes

Current package version: 0.1.0b1.

ari-core is in beta and actively evolving. Some APIs and conventions may change as the framework matures, especially around runtime and workflow authoring ergonomics.

For now:

• Pin versions for production workflows
• Review changelogs/release notes before upgrading
• Re-run tests after each upgrade

License

This project is licensed under the terms of the license defined in this repository.