portfolio-optimiser/docs/bestille-en-kjoring.md

Bestille en kjøring

Dette dokumentet er for deg som bestiller en kjøring — fagpersonen som vet hvilke tilnærminger det er verdt å prøve på et prosjekt, og som vil vite nøyaktig hva systemet skal gjøre før det gjør det. Søsterdokumentet ekspert-svar.md handler om det motsatte enden: å avgi dommen etterpå.

Ærlighetsmerking. Bestillingen styrer hva som vurderes. Den styrer aldri hva som godkjennes. Den deterministiske validatoren gjelder uendret for en tilnærming du selv har bedt om — ber du om noe tallene ikke bærer, blir det avvist, og avvisningen kommer tilbake til deg med begrunnelsen.

Oppdragsfila

En bestilling er én JSON-fil. Du gir den til kjøringen med --mandate.

{
  "objective": "Kutt energikostnad i BYGG-KONTOR-NORD uten ombygging, med tiltak som kan gjennomføres i 2026.",
  "approaches": [
    {
      "id": "led-retrofit",
      "label": "LED-retrofit av kontorbelysning",
      "description": "Drift mener armaturene er originale og har gått langt forbi oppgitt levetid."
    },
    {
      "id": "driftsavtale",
      "label": "Reforhandling av driftsavtale",
      "description": "Avtalen er ikke justert siden 2019 og dekker areal vi ikke lenger disponerer."
    }
  ],
  "allow_own_proposals": true,
  "success_criteria": "Minst ett tiltak som passerer validatoren og som drift kan stå inne for."
}

Felt	Hva det gjør
objective	Hva kjøringen er til for, i klartekst. Påkrevd — en kjøring uten uttalt hensikt er nettopp det denne fila finnes for å hindre.
approaches	Tilnærmingene du vil ha vurdert. Hver får sin egen vurdering og sin egen linje i oppgjøret.
allow_own_proposals	true (standard): systemet foreslår også sitt eget, i tillegg til dine. false: kun dine.
success_criteria	Hva du vil regne som vellykket. Gjengis ordrett i kunngjøringen; ingenting tolker den maskinelt.

Om id: den er nøkkelen tilnærmingen rapporteres under. To tilnærminger kan ikke dele id (da ville de kollapset til én linje i oppgjøret), og own-proposal er reservert for systemets eget forslag.

Om description: den mates ordrett inn til modellen. Det er her fagkunnskapen din faktisk gjør en forskjell — hvorfor du tror tilnærmingen er verdt å prøve er nøyaktig det systemet ikke kan lese seg til av kostnadstallene.

Enten tilnærminger eller egne forslag. En fil med tom approaches og allow_own_proposals: false blir avvist: da har kjøringen ingenting å gjøre.

Å kjøre den

uv run python -m portfolio_optimiser.run BYGG-KONTOR-NORD \
  --docs-dir shared/examples/bygg-energi-mikro \
  --bundle-dir shared/examples/bygg-energi-mikro \
  --mandate oppdrag.json \
  --scripted-replies replies.json

--mandate virker i begge moduser. I porteføljemodus (--portfolio) gjelder bestillingen hvert prosjekt i passet, og hvert prosjekt gjør opp for seg.

Vil du se hva kjøringen ville gjort, uten å bruke penger? Legg til --live-dry-run. Da skrives kunngjøringen, og kjøringen stopper før første modellkall.

Fila leses strengt. Mangler den, eller er den feilformet, blir kjøringen nektet (rc 1) — den går aldri videre på en halvlest bestilling. Det er med vilje: et oppgjør som beskriver arbeid ingen har bestilt, er verre enn ingen bestilling.

Hva du får: kunngjøringen

Før noe koster penger, skriver kjøringen hva den skal gjøre:

Run mandate for BYGG-KONTOR-NORD
  Objective:   Kutt energikostnad i BYGG-KONTOR-NORD uten ombygging, ...
  Evaluates:   2 expert-proposed approach(es) + the system's own proposals
                 1. led-retrofit — LED-retrofit av kontorbelysning
                 2. driftsavtale — Reforhandling av driftsavtale
  Stops at:    3 rounds / 100000 tokens
  Contacts:    no external services
  Success:     Minst ett tiltak som passerer validatoren ...

Kjører du med --dimension-config, kommer det en Scoped to:-linje til. Linjer for ting kjøringen ikke har — avgrensning, tallmål — utelates i stedet for å stå tomme: en tom linje ville lest som en beslutning ingen har tatt.

Contacts er egress-erklæringen: en kjøring når aldri en ekstern tjeneste den ikke har navngitt her. Stops at er takene — systemet kjører aldri en ubegrenset løkke.

Hva du får: oppgjøret

Etter kjøringen svarer den for bestillingen, én linje per tilnærming:

Mandate outcome
  led-retrofit         VALIDATED          30000 NOK   LED-retrofit av kontorbelysning
  driftsavtale         REJECTED      claimed 240000 exceeds feasible 90000
  own-proposal         NOT EVALUATED budget exhausted before this approach was evaluated
  Validated: 1 of 3 approaches — best 30000 NOK (the outcome this run carries)

De tre statusene betyr forskjellige ting, og forskjellen er poenget:

• VALIDATED — tallene holdt. Beløpet er det validatoren slapp gjennom.
• REJECTED — tilnærmingen ble vurdert, og falt på tallene. Grunnen står der; det er den du kan gjøre noe med (ofte er den «regnet mot feil grunnlag», ikke «dårlig idé»).
• NOT EVALUATED — kjøringen rakk den aldri. Den er ikke avvist, og den er ikke glemt.

En tilnærming du bestilte forsvinner aldri i stillhet. Det er hele grunnen til at oppgjøret finnes.

Tilnærmingene summeres ikke. Flere av dem angriper som regel samme kostnadslinje, så de er alternativer — ikke besparelser som legges oppå hverandre. Derfor står det hvor mange som holdt og hvilken kjøringen bærer videre, aldri en sum. (Dette ble oppdaget ved å faktisk kjøre den: tre tilnærminger mot samme linje ga «totalt 90 000», som ingen av dem kunne innfri.)

Hver tilnærming kan dømmes for seg

Kjører du med --outbox-dir (og --run-id), legger kjøringen igjen én artefakt per vurdert tilnærming — run-001-led-retrofit-proposal.json, run-001-driftsavtale-proposal.json, og så videre — ikke bare for den kjøringen bar videre.

Det er ikke en bokføringsdetalj. Uten det kunne bare den valgte tilnærmingen få en fagdom, og de andre du bestilte ville aldri nådd læringssløyfa: de ble vurdert, rapportert i oppgjøret, og deretter glemt. Nå står de hver for seg i køen din:

uv run python -m portfolio_optimiser.hitl pending --outbox-dir utboks --verdict-dir innboks
run-001 c91cb2fe1aa139a9 validated [led-retrofit]
run-001 4f0a1d77b2e5c318 rejected [driftsavtale]

Hvordan du svarer på dem står i ekspert-svar.md. En tilnærming med status NOT EVALUATED har ingen artefakt — kjøringen produserte aldri et forslag for den, så det er ingenting å dømme.

Hva bestillingen ikke gjør

• Den overstyrer ikke validatoren. Se ærlighetsmerkingen øverst.
• Den avgjør ikke om et tiltak skal gjennomføres. Det gjør et menneske, etterpå — se ekspert-svar.md.
• Den setter ikke et tallmål. Sparemålet har ett hjem, målkonfigurasjonen (--goals, som gjelder porteføljemodus). To kopier av samme tall drifter fra hverandre, så oppdraget bærer hensikten i ord og gjengir tallet hvis det finnes.
• Den lagrer seg ikke som kunnskap. Bestillingen er en instruks for én kjøring. Det som lærer systemet noe, er dommen du avgir etterpå.

Hvis kjøringen skal spørre en ekstern tjeneste

Skal agentene kunne slå opp i en tjeneste dere allerede har — et prisregister, målerdata, et avtaleregister — settes den opp med --mcp-config:

{"servers": [
  {"name": "prisregister", "transport": "http", "url": "https://intern.example/mcp",
   "allowed_tools": ["lookup_unit_price"], "timeout_seconds": 15,
   "credential_env": "PRISREGISTER_TOKEN"}
]}

Tre ting er verdt å vite som bestiller:

• Du må navngi hvilke verktøy som er tillatt. Tom liste er ikke lov. Uten det ville tjenesten selv bestemt hva agentene får lov til å kalle.
• Alt som vil bli kontaktet, står i kunngjøringen — før første kall, på Contacts:-linja, med både servernavn og tillatte verktøy. En kjøring når aldri en tjeneste den ikke har navngitt. Det gjelder også når du ikke bruker --mandate.
• Passord og nøkler skal aldri i fila. credential_env navngir en miljøvariabel; verdien leses derfra. Er variabelen ikke satt, blir kjøringen nektet — heller det enn å ringe tjenesten anonymt og få svar med feil tilgang.

Uten --mcp-config gjøres ingen nettverkskall i det hele tatt.

Etterpå: hva ble faktisk kalt

Kunngjøringen er en tillatelse — den sier hva kjøringen kan kontakte. Den sier ikke om agentene brukte tjenesten eller lot den ligge. Derfor fører kjøringen også et kall-spor, som følger med artefaktene under provenance.external_calls:

"external_calls": [{"server": "prisregister", "tool": "lookup_unit_price"}]

En tom liste er en påstand, ikke et hull: ingenting utenfor prosessen ble kontaktet. Verktøy som kjører lokalt (som dokumentsøket) telles ikke med — de er ikke kontakt med noen.

Hva sporet ikke sier. Det viser at verktøyet ble kalt, og hvilken server det tilhører. Det er ikke bevis for at tjenestens svar er det tallet som havnet i forslaget, og det er ingen kontrollert gjengivelse av hva tjenesten svarte. Skal svaret etterprøves, må det gjøres mot tjenesten selv.

En sjelden detalj, tatt med fordi den ellers ville sett ut som en feil: hvis to servere tilbyr verktøy med samme navn, står server tomt. Rammeverket oppgir bare verktøynavnet, så de to lar seg ikke skille — og da er «vet ikke» riktigere enn å gjette på den ene.