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 appworkflow.py: verzameld al je workflow stappen en groepeerd zesteps/: bevat alle stappen voor de workflowsdocs/: alle documentatie hoeari-corete 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 kiezenconfirm(...): gebruiker moet iets bevestigenui(...): gebruiker krijgt een UI-element te zien, bijvoorbeeld eenDocumentViewerof 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.