Metadata-Version: 2.4
Name: ari-core
Version: 0.1.0b1
Summary: Core workflow engine and OSS runtime for Ari
Author-email: Tom Laumen <tom@ari.engineer>
License: Commons Clause License Condition v1.0
        
        The Software is provided to you by the Licensor under the License,
        as defined below, subject to the following condition.
        
        Without limiting other conditions in the License, the grant of rights
        under the License will not include, and the License does not grant to
        you, the right to Sell the Software.
        
        For purposes of the foregoing, "Sell" means practicing any or all of
        the rights granted to you under the License to provide to third parties,
        for a fee or other consideration (including without limitation fees for
        hosting or consulting/support services related to the Software), a
        product or service whose value derives, entirely or substantially, from
        the functionality of the Software. Any license notice or attribution
        required by the License must also include this Commons Clause License
        Condition notice.
        
        Software: ari-core
        License: MIT
        Licensor: ARI.engineer
        
        ---
        
        MIT License
        
        Copyright (c) 2026 ARI.engineer
        
        Permission is hereby granted, free of charge, to any person obtaining
        a copy of this software and associated documentation files (the
        "Software"), to deal in the Software without restriction, including
        without limitation the rights to use, copy, modify, merge, publish,
        distribute, sublicense, and/or sell copies of the Software, and to
        permit persons to whom the Software is furnished to do so, subject to
        the following conditions:
        
        The above copyright notice and this permission notice shall be included
        in all copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
        EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
        MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
        IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
        CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
        TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
        SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
License-File: LICENSE
Requires-Python: >=3.12
Requires-Dist: prompt-toolkit>=3.0.47
Requires-Dist: pydantic>=2.11.7
Description-Content-Type: text/markdown

# ari-core

> AI workflows for engineer that actually work.

![Python](https://img.shields.io/badge/python-3.12%2B-blue)
![Version](https://img.shields.io/badge/version-0.1.0b1-informational)

Quick links: [Getting Started](ari_core/docs/getting-started.md) · [Core Concepts](ari_core/docs/core-concepts.md) · [API Cheatsheet](ari_core/docs/api-cheatsheet.md)

## 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`](https://docs.astral.sh/uv/) (recommended)

### Install

```bash
uv add ari-core
```

### Verify

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

## Quick Start (2-minute example)

Create a new workflow project:

```bash
uv run ari new my-workflow
cd my-workflow
```

Run locally:

```bash
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](ari_core/docs/step-authoring.md)
- [Segment Guide](ari_core/docs/segment-guide.md)

## 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](ari_core/docs/ui-components.md).

## Running locally

Run your workflow project locally:

```bash
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:

```bash
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:

```bash
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](ari_core/docs/core-concepts.md)
- [API Cheatsheet](ari_core/docs/api-cheatsheet.md)
- [Getting Started](ari_core/docs/getting-started.md)
- [Step Authoring](ari_core/docs/step-authoring.md)
- [Step Contracts and Errors](ari_core/docs/step-contracts-and-errors.md)
- [UI Components](ari_core/docs/ui-components.md)
- [Segment Guide](ari_core/docs/segment-guide.md)
- [Database Guide](ari_core/docs/database-guide.md)
- [Publish to Demo](ari_core/docs/publish-to-demo.md)
- [Issues and Questions](ari_core/docs/issues.md)

## Contributing / development

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

### Before you start

- Check existing guidance in [Issues and Questions](ari_core/docs/issues.md)
- If you are unsure about direction, open an issue first to discuss approach

### Local development

```bash
cd packages/ari-core
uv sync
```

### Run tests

```bash
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](ari_core/docs/issues.md)

## 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.
