← Alle blogs AI MET EEN BOUWHELM OP

Van terminal naar team: bouw je eerste AI workflow met ARI

Een AI workflow is geen chatbot met voorgedefinieerde stappen. Het is een manier om vast te leggen waar code rekent, waar AI helpt en waar de ingenieur controle houdt.

In de vorige posts hebben we het gehad over principes:

  • zet AI niet in waar deterministische code beter is
  • maak AI functies betrouwbaar met routing, context en evals
  • begin klein en verzamel data uit echt gebruik

Allemaal goed en wel, maar hoe bouw je zoiets nou daadwerkelijk?!

In dit blog maken we een eerste workflow met ari-core. We bouwen de workflow eerst lokaal en delen hem daarna in een webapp in de demo omgeving.

Als voorbeeld maken we een (uitgekleedde) stabiliteitsberekening.

Waarom het ARI framework?

Jacob Lauritzen van Legora vatte het in een AI engineer praatje goed samen:

“The ceiling of chat interfaces isn’t a UX problem. It’s a verification problem.”

In onze wereld is dit direct herkenbaar. Je kan aan een AI vragen: “maak een stabiliteitsrapport”. Dan krijg je waarschijnlijk een uiteenzetting die er goed uitziet. Maar hoe is de berekening gedaan? Welke parameters zijn gebruikt? En hoe kun jij eenvoudig controleren of dit klopt en bijsturen als dat niet zo is?

Met een workflow maak je die stappen expliciet.

De berekening blijft code en om mee te beginnen mag de LLM helpen met tekstverwerking. Waar stappen geautomatiseerd of met AI worden uitgevoerd, zorgen de primitieven in ari-core ervoor dat je de gebruiker van een workflow op intuitieve wijze invloed kan uitoefenen op de gewenste uitkomst. De controle blijft zo bij de ingenieur.

Wat gaan we bouwen?

In deze blog gaan we een (versimpelde versie van een) stabiliteitsberekening maken om een conceptueel begrip op te bouwen. In de volgende blog gaan we de workflow dan vervolgens ‘productie klaar’ maken, een versie waar een ingenieur dan ook echt mee zou willen werken!

De eerste versie van de workflow ziet er als volgt uit:

Grondprofiel invoeren
        ↓
Parameters invoeren
        ↓
Geometrie invoeren
        ↓
Stabiliteitsberekening uitvoeren
        ↓
Conceptrapport schrijven
        ↓
Feedback van de gebruiker verwerken

De stabiliteitsberekening komt uit een open-source Pythonpakket voor stabiliteit, xslope. Zo blijft de tutorial bruikbaar voor iedereen, dus even geen D-Stability, Slope/W of andere commerciële software. De rapporttekst komt uit een AI-functie. De ingenieur geeft vervolgens feedback om de rapportage te verbeteren wat de LLM weer gebruikt.

Aan het einde pushen we de workflow naar een demo-omgeving:

uv run ari demo-push

Daarmee draait dezelfde workflow in een webapp, lekker makkelijk om te delen.

Project opzetten

ARI gebruikt uv als package manager. Allereerst installeren we de benodigde python pakketten:

uv init --bare <your app name>
uv add ari-core xslope tabulate openai anthropic

Een nieuw project aanmaken met ari doe je als volgt:

uv run ari new

Dit creëert de volgende structuur:

ari-project/
├── .env.example
├── LLM_GUIDE.md
├── README.md
├── main.py
├── workflow.py
│
├── steps/
│   ├── __init__.py
│   └── example_step.py
│
└── docs/
    ├ ...

Van het raamwerk opgezet bevat de volgende zaken:

  • main.py: runt uiteindelijk je app
  • workflow.py: verzameld al je workflow stappen en groepeerd ze
  • steps/: bevat alle stappen voor de workflows
  • docs/: alle documentatie hoe ari-core te gebruiken

Ook bevat het raamwerk een README.md voor jou als developer en een LLM_GUIDE.md, zodat je AI coding agent de structuur van het project begrijpt en je kan ondersteunen.

Vanaf nu gaan we zo goed als uitsluitend aan het werk in steps/, de rest staat al goed ingesteld..

De bouwstenen

Een ARI workflow bestaat uit drie simpele onderdelen.

Een DataModel beschrijft de data die door je workflow stroomt. Denk aan grondlagen, parameters, geometrie, rekenresultaten of rapporttekst.

Een Step doet één ding. Bijvoorbeeld: vraag het grondprofiel uit, voer geometrie in, voer een berekening uit of genereer een rapport. De Step voert dit uit via de execute(self, ctx) methode die je voor elke Step zelf moet definiëren. Hierin kun je een gebruiker vragen om input, LLM call doen, een rekenpakket runnen, of een combinatie van deze dingen. Gewoon in python definiëren wat jij wil doen.

Voor interactie met de gebruiker kent ari-core op dit moment vier primitieven, sterk geïnspireerd door prompt-toolkit:

  • prompt(...): gebruiker krijgt een open vraag (tekst als antwoord)
  • choice(...): gebruiker moet een optie kiezen
  • confirm(...): gebruiker moet iets bevestigen
  • ui(...): gebruiker krijgt een UI-element te zien, bijvoorbeeld een DocumentViewer of een zelf geïmplementeerde component

Een Segment is vervolgens een workflow: een lijst van steps in de volgorde waarin ze uitgevoerd worden.

Daarnaast kent ARI twee plekken om data op te slaan:

  • Table.WORKFLOW: data voor één berekening, hier slaan we in deze blog alles in op!
  • Table.PROJECT: data integraal voor het project, hier komen we in de volgende blog op terug

Deel 1 — Een eerste stabiliteitsworkflow

We beginnen bewust eenvoudig. Aan het eind van dit blog heb je nog niet de workflow zoals je hem als ingenieur uiteindelijk zou willen gebruiken, maar je hebt wel de belangrijkste concepten geleerd. De workflow verfijnen doen we in de volgende blog!

Stap 1 — Grondprofiel invoeren

De gebruiker voert een eenvoudig grondprofiel in.

Bijvoorbeeld:

NAP +8.0 m tot NAP +5.0 m: klei
NAP +5.0 m tot NAP +1.0 m: zand
NAP +1.0 m tot NAP -2.0 m: vaste zandlaag

Deze step produceert grondprofiel en bewaart dat in Table.WORKFLOW.

De helper as_float(...) maakt de conversie van tekst met eventueel een komma naar een floating point getal.

from __future__ import annotations

from ari_core.models import DataModel, Table
from ari_core.prompting import confirm, prompt
from ari_core.workflow.step import Product, Step, StepContext


def as_float(value: object) -> float:
    return float(str(value).replace(",", "."))


class Grondlaag(DataModel):
    bovenkant: float
    onderkant: float
    materiaal: str


class Grondprofiel(DataModel):
    lagen: list[Grondlaag]
    grondwaterstand_nap: float


class VoerGrondprofielInStep(Step):
    name = "voer_grondprofiel_in"
    requires = []
    produces = [Product(key="grondprofiel", dest=Table.WORKFLOW)]

    def execute(self, ctx: StepContext) -> None:
        maaiveld_nap = prompt("Wat is het maaiveldniveau (NAP)?")

        lagen: list[Grondlaag] = []
        huidige_bovenkant = as_float(maaiveld_nap)

        while True:
            laag_nr = len(lagen) + 1
            onderkant = prompt(f"Laag {laag_nr} - onderkant (NAP):")
            materiaal = prompt(f"Laag {laag_nr} - materiaal:")

            lagen.append(
                Grondlaag(
                    bovenkant=huidige_bovenkant,
                    onderkant=as_float(onderkant),
                    materiaal=str(materiaal).strip(),
                )
            )

            huidige_bovenkant = as_float(onderkant)

            doorgaan = confirm("Nog een laag toevoegen?", default=False)
            if not doorgaan:
                break

        grondwaterstand_nap = prompt("Wat is de grondwaterstand (NAP)?")

        ctx["grondprofiel"] = Grondprofiel(
            lagen=lagen,
            grondwaterstand_nap=as_float(grondwaterstand_nap),
        )

Stap 2 — Parameters invoeren

Vervolgens moeten we de materiaalparameters opgeven per grondsoort. In een projectcontext haal je dit bijvoorbeeld met een LLM uit een uitgangspuntennotitie. Voor een enkele berekening kan de ingenieur zelf een inschatting geven op basis van grondonderzoek, historische data en engineering judgement.

Voor het uitrekenen van de stabiliteit rekenen we met het Mohr-Coulomb sterkte model. De parameters zijn dan:

  • volumiek gewicht
  • cohesie
  • hoek van inwendige wrijving

Deze step grondprofiel (product van de vorige stap) als input nodig. We moeten immers weten welke grondsoorten er gedefinieerd zijn. De output zijn de materiaal_parameters.

from __future__ import annotations

from ari_core.models import DataModel, Table
from ari_core.prompting import prompt
from ari_core.workflow.step import Product, Requirement, Step, StepContext

from steps.voer_grondprofiel_in import Grondprofiel, as_float


class GrondsoortParameters(DataModel):
    volumiek_gewicht_kN_m3: float
    cohesie_kPa: float
    wrijvingshoek_graden: float


class MateriaalParameters(DataModel):
    per_materiaal: dict[str, GrondsoortParameters]


class VoerParametersInStep(Step):
    name = "voer_parameters_in"
    requires = [Requirement(key="grondprofiel", source=Table.WORKFLOW, model=Grondprofiel)]
    produces = [Product(key="materiaal_parameters", dest=Table.WORKFLOW)]

    def execute(self, ctx: StepContext) -> None:
        grondprofiel: Grondprofiel = ctx["grondprofiel"]
        materialen = sorted({laag.materiaal for laag in grondprofiel.lagen})

        per_materiaal: dict[str, GrondsoortParameters] = {}

        for naam in materialen:
            gamma = prompt(f"{naam} - volumiek gewicht (kN/m3):")
            cohesie = prompt(f"{naam} - cohesie (kPa):")
            phi = prompt(f"{naam} - wrijvingshoek (graden):")

            per_materiaal[naam] = GrondsoortParameters(
                volumiek_gewicht_kN_m3=as_float(gamma),
                cohesie_kPa=as_float(cohesie),
                wrijvingshoek_graden=as_float(phi),
            )

        ctx["materiaal_parameters"] = MateriaalParameters(per_materiaal=per_materiaal)

Stap 3 — Geometrie invoeren

Vervolgens is de geometrische data nodig. In de praktijk verkrijgen we de data meestal:

  • met een API uit ACC halen
  • uit een plaatje abstraheren middels AI
  • uit een gestandaardiseerde spreadsheet inlezen
  • zelf tekenen, bijvoorbeeld bij een stabiliteitsmaatregel in het dijkontwerp

Om de demo echter simpel te houden, voeren we de geometrie voor nu even in als puntenlijst via een prompt(...) en zetten die daarna om naar workflowdata. Mochten we echter een van deze aanpassingen willen maken, is dit voor het bouwen van de workflow slechts een minimale aanpassing!

De helper parse_geometriepunten(...) houdt de string-parsing buiten de step-logica. De volledige helper staat in de repository bij dit artikel.

from __future__ import annotations

from ari_core.models import DataModel, Table
from ari_core.prompting import prompt
from ari_core.workflow.step import Product, Step, StepContext

from steps.voer_grondprofiel_in import as_float


class GeometriePunt(DataModel):
    x: float
    z: float


class Geometrie(DataModel):
    punten: list[GeometriePunt]


class LaadGeometrieStep(Step):
    name = "laad_geometrie"
    requires = []
    produces = [Product(key="geometrie", dest=Table.WORKFLOW)]

    def execute(self, ctx: StepContext) -> None:
        punten = prompt(
            "Geef maaiveldpunten als x,z-paren gescheiden door puntkomma's. "
            "Voorbeeld: 0,8.0; 10,7.5; 20,5.0"
        )

        ctx["geometrie"] = Geometrie(
            punten=parse_geometriepunten(punten)
        )

Stap 4 — Stabiliteitsberekening uitvoeren

We nemen aan dat er geen constructies, maaiveldbelastingen of andere externe belastingen zijn. Dan hebben we nu alle gegevens om een simpele stabiliteitsberekening te maken. https://www.youtube.com/watch?v=XNtkiQJ49Ps De workflow gebruikt het grondprofiel, de materiaalparameters en de geometrie als input voor het pythonpakket dat de stabiliteit berekent.

De uitkomst uit de berekening is:

  • veiligheidsfactor
  • middelpunt en straal van de maatgevende glijcirkel

De helper build_slope_data(...) zet de workflowdata om naar het formaat van de rekenkern. run_analysis(...) voert de xslope-analyse uit en geeft de maatgevende resultaten terug. De volledige implementatie staat in de repository bij dit artikel.

Nu kunnen we eenvoudig en overzichtelijk een step maken die de berekening uitvoert. Omdat we in deze step geen AI gebruiken maar gewone rekensoftware, hoeven we ons geen zorgen te maken dat een taalmodel de stabiliteitsberekening verkeerd uitvoerd.

from __future__ import annotations

from ari_core.models import DataModel, Table
from ari_core.prompting import ui
from ari_core.workflow.step import Product, Requirement, Step, StepContext

from .helpers.xslope_engine import build_slope_data, run_analysis
from steps.laad_geometrie import Geometrie
from steps.voer_grondprofiel_in import Grondprofiel
from steps.voer_parameters_in import MateriaalParameters


class StabiliteitsResultaat(DataModel):
    veiligheidsfactor: float
    maatgevende_cirkel_x0: float
    maatgevende_cirkel_y0: float
    maatgevende_cirkel_r: float


class BerekenStabiliteitStep(Step):
    name = "bereken_stabiliteit"
    requires = [
        Requirement(key="grondprofiel", source=Table.WORKFLOW, model=Grondprofiel),
        Requirement(key="materiaal_parameters", source=Table.WORKFLOW, model=MateriaalParameters),
        Requirement(key="geometrie", source=Table.WORKFLOW, model=Geometrie),
    ]
    produces = [Product(key="stabiliteitsresultaat", dest=Table.WORKFLOW)]

    def execute(self, ctx: StepContext) -> None:
        grondprofiel: Grondprofiel = ctx["grondprofiel"]
        materiaal_parameters: MateriaalParameters = ctx["materiaal_parameters"]
        geometrie: Geometrie = ctx["geometrie"]

        slope_data = build_slope_data(
            grondprofiel=grondprofiel,
            materiaal_parameters=materiaal_parameters,
            geometrie=geometrie,
        )
        analyse = run_analysis(slope_data, num_slices=30, include_plot=True)

        plot_base64 = analyse.get("plot_base64")
        if plot_base64:
            ui(SlipcircleViewerComponent(plot_base64, analyse["veiligheidsfactor"]))

        ctx["stabiliteitsresultaat"] = StabiliteitsResultaat(
            veiligheidsfactor=analyse["veiligheidsfactor"],
            maatgevende_cirkel_x0=analyse["maatgevende_cirkel_x0"],
            maatgevende_cirkel_y0=analyse["maatgevende_cirkel_y0"],
            maatgevende_cirkel_r=analyse["maatgevende_cirkel_r"],
        )

Stap 5 — Conceptrapport genereren

Met de berekening gemaakt kunnen we het rapport schrijven. Het rapporteren is met deze opzet ook een overzichtelijk probleem, want we:

  • hebben alle data gestructureerd opgeslagen
  • zijn expliciet betrokken in de aannames voor de berekening
  • hebben een simpele interface om een AI-functie aan te roepen die het rapport voor ons schrijft

We hoeven ons dus enkel nog druk te maken dat de context van het model goed benut wordt zodat de LLM een mooi rapport voor ons maakt!

De helper genereer_rapport(...) maakt de rapporttekst in markdown op basis van de gestructureerde invoer. De volledige implementatie staat in de repository bij dit artikel. Later gebruiken we dezelfde helper opnieuw met feedbackpunten.

Met ui(DocumentViewer(...)) tonen we het markdownrapport in de browser.

Let wel op: je moet zelf je API key van de modelprovider in de .env laden. Hiervoor zijn een paar API’s van modelproviders toegevoegd aan de genereer_rapport(...) functie. Pas echter op dat je deze key niet naar de demo-omgeving pushed!

from __future__ import annotations

from ari_core.models import DataModel, Table
from ari_core.prompting import ui
from ari_core.workflow.step import Product, Requirement, Step, StepContext

from .helpers.document_viewer import DocumentViewer
from .helpers.rapport_generator import genereer_rapport
from steps.bereken_stabiliteit import StabiliteitsResultaat
from steps.laad_geometrie import Geometrie
from steps.voer_grondprofiel_in import Grondprofiel
from steps.voer_parameters_in import MateriaalParameters


class ConceptRapport(DataModel):
    titel: str
    inhoud_markdown: str


class GenereerRapportStep(Step):
    name = "genereer_rapport"
    requires = [
        Requirement(key="grondprofiel", source=Table.WORKFLOW, model=Grondprofiel),
        Requirement(key="materiaal_parameters", source=Table.WORKFLOW, model=MateriaalParameters),
        Requirement(key="geometrie", source=Table.WORKFLOW, model=Geometrie),
        Requirement(key="stabiliteitsresultaat", source=Table.WORKFLOW, model=StabiliteitsResultaat),
    ]
    produces = [Product(key="concept_rapport", dest=Table.WORKFLOW)]

    def execute(self, ctx: StepContext) -> None:
        grondprofiel: Grondprofiel = ctx["grondprofiel"]
        materiaal_parameters: MateriaalParameters = ctx["materiaal_parameters"]
        geometrie: Geometrie = ctx["geometrie"]
        stabiliteitsresultaat: StabiliteitsResultaat = ctx["stabiliteitsresultaat"]

        inhoud = genereer_rapport(
            grondprofiel=grondprofiel,
            materiaal_parameters=materiaal_parameters,
            geometrie=geometrie,
            stabiliteitsresultaat=stabiliteitsresultaat,
            feedback_pointers=None,
        )

        concept_rapport = ConceptRapport(
            titel="Concept stabiliteitsrapport",
            inhoud_markdown=inhoud,
        )

        ui(DocumentViewer(concept_rapport.titel, concept_rapport.inhoud_markdown))

        ctx["concept_rapport"] = concept_rapport

Stap 6 — Feedback vragen en geaccepteerde versie opslaan

De conceptrapportage bevat zonder twijfel tekortkomingen. De ingenieur moet dus feedback kunnen geven.

In Stap 5 is het conceptrapport al getoond met DocumentViewer. In deze step vragen we de gebruiker één of meer pointers via prompt(...). Die pointers geven we mee aan de LLM om een nieuw rapport te maken met de genereer_rapport functie. De aangepaste versie tonen we weer met DocumentViewer.

Later kan dit een rijkere UI-component worden waarbij je, zoals in ChatGPT, een stuk tekst selecteert en prompt wat je daarmee wilt.

from __future__ import annotations

from ari_core.models import DataModel, Table
from ari_core.prompting import confirm, prompt, ui
from ari_core.workflow.step import Product, Requirement, Step, StepContext

from .helpers.document_viewer import DocumentViewer
from .helpers.rapport_generator import genereer_rapport
from steps.bereken_stabiliteit import StabiliteitsResultaat
from steps.laad_geometrie import Geometrie
from steps.voer_grondprofiel_in import Grondprofiel
from steps.voer_parameters_in import MateriaalParameters


class RapportFeedback(DataModel):
    opmerkingen: list[str]


class GeaccepteerdRapport(DataModel):
    inhoud_markdown: str


def vraag_pointers() -> list[str]:
    pointers: list[str] = []

    while True:
        opmerking = prompt("Welke opmerking wil je meegeven voor de volgende rapportversie?")
        pointers.append(str(opmerking).strip())

        doorgaan = confirm("Nog een opmerking toevoegen?", default=False)
        if not doorgaan:
            break

    return pointers


class VraagRapportFeedbackStep(Step):
    name = "vraag_rapport_feedback"
    requires = [
        Requirement(key="grondprofiel", source=Table.WORKFLOW, model=Grondprofiel),
        Requirement(key="materiaal_parameters", source=Table.WORKFLOW, model=MateriaalParameters),
        Requirement(key="geometrie", source=Table.WORKFLOW, model=Geometrie),
        Requirement(key="stabiliteitsresultaat", source=Table.WORKFLOW, model=StabiliteitsResultaat),
    ]
    produces = [
        Product(key="rapport_feedback", dest=Table.WORKFLOW),
        Product(key="geaccepteerd_rapport", dest=Table.WORKFLOW),
    ]

    def execute(self, ctx: StepContext) -> None:
        grondprofiel: Grondprofiel = ctx["grondprofiel"]
        materiaal_parameters: MateriaalParameters = ctx["materiaal_parameters"]
        geometrie: Geometrie = ctx["geometrie"]
        stabiliteitsresultaat: StabiliteitsResultaat = ctx["stabiliteitsresultaat"]

        pointers = vraag_pointers()

        aangepaste_rapporttekst = genereer_rapport(
            grondprofiel=grondprofiel,
            materiaal_parameters=materiaal_parameters,
            geometrie=geometrie,
            stabiliteitsresultaat=stabiliteitsresultaat,
            feedback_pointers=pointers,
        )

        ui(DocumentViewer("Aangepast stabiliteitsrapport", aangepaste_rapporttekst))

        ctx["rapport_feedback"] = RapportFeedback(opmerkingen=pointers)
        ctx["geaccepteerd_rapport"] = GeaccepteerdRapport(inhoud_markdown=aangepaste_rapporttekst)

Segment registreren

Nu hebben we zes Step-klassen gedefinieerd. Deze komen samen in een Segment in de SegmentRegistry. Om de implementatie voor de tutorial simpel te houden maken we er een Segment van, hoewel we dit in de praktijk waarschijnlijk overal waar er meerdere opties zijn voor de input, zoals ook benoemd in dit blog, zouden kunnen/willen opknippen. Ook geven we het Segment een naam en beschrijving mee zodat het eenvoudig te herkennen is wat het doet.

De volgende stappen zijn inmiddels gebouwd:

VoerGrondprofielIn
VoerParametersIn
LaadGeometrie
BerekenStabiliteit
GenereerRapport
VraagRapportFeedback

Die registreren we als één segment in workflow.py:

from ari_core.workflow.registry import SegmentRegistry
from ari_core.workflow.segment import Segment

from steps.bereken_stabiliteit import BerekenStabiliteitStep
from steps.genereer_rapport import GenereerRapportStep
from steps.laad_geometrie import LaadGeometrieStep
from steps.voer_grondprofiel_in import VoerGrondprofielInStep
from steps.voer_parameters_in import VoerParametersInStep
from steps.vraag_rapport_feedback import VraagRapportFeedbackStep


registry = SegmentRegistry()

registry.register(
    Segment(
        name="stabiliteitsrapportage",
        description="Voer grondgegevens in, bereken stabiliteit en rond een rapport af",
        steps=[
            VoerGrondprofielInStep,
            VoerParametersInStep,
            LaadGeometrieStep,
            BerekenStabiliteitStep,
            GenereerRapportStep,
            VraagRapportFeedbackStep,
        ],
        requires=[],
    )
)

Met de SegmentRegistry gedefinieerd kunnen we onze ari-core applicatie runnen. Deze registry wordt in main.py ingeladen.
Run je eigen workflow lokaal met:

uv run main.py

Dat is goed om te bouwen. Maar het wordt pas echt interessant als je de workflows met collega’s kan delen.

Hiervoor is er een demo omgeving gemaakt (toegang aanvragen, zie einde blog):

uv run ari demo-push

ARI publiceert de workflow naar een apart platform wat de web app host.

Je eerste workflow!

Dit was alles wat je nodig hebt om ari-core uit te proberen!

Je hebt een workflow die:

  • gestructureerde invoer verzamelt
  • een deterministische stabiliteitsberekening uitvoert
  • een AI-conceptrapport schrijft
  • menselijke feedback vastlegt
  • naar een browserdemo gepusht kan worden

Bouw deze versie, probeer de verschillende ari-core primitieven uit en zie hoe makkelijk je iets bouwt en kan delen met anderen!

De volledige implementatie van deze basisworkflow staat in de repository bij deze post. Daar vind je ook de helperfuncties voor de stabiliteitsberekening en de rapportgenerator.

Wil je toegang om je workflow te delen met anderen? Vraag toegang aan via brugnaarai.nl.

Deze workflow is momenteel nog te rudimentair om echt goede gebruikers interactie te hebben. Hier komen we in het volgende blog op terug!

Heb je vragen of wil je sparren over een specifieke workflow? Reageer op LinkedIn, maak een issue op ari-core of neem contact met mij op via tom@ari.engineer.

Vertel ons waar je tegenaan loopt.