portfolio-optimiser/DEPLOY.md

Deploying and using this package

This archive is a complete, self-contained copy of portfolio-optimiser. You do not need to clone anything or have an account anywhere to deploy it. Unzip it and follow this document.

It is written in English because its readers are implementing developers and platform operators. The two documents that describe the human side of the loop are written in Norwegian and ship in this same archive: docs/bestille-en-kjoring.md (ordering a run) and docs/ekspert-svar.md (giving the verdict).

---

1. What this is — and what it is not

It finds cost savings inside a single project: agents propose candidate measures, a deterministic validator decides whether the numbers hold, a second agent (the "checker") gates the reasoning, and a domain expert gives the final verdict. The system learns from those verdicts.

There is no chat interface, and that is a design decision rather than a missing feature.

The hosted surface is a task API — POST /invocations with a JSON body, GET /readiness — not a conversation. The system is deliberately not exposed as a Microsoft Foundry agent via as_agent(), because the validator, the cost-baseline anchoring, the checker gate and the savings ledger all live outside the agent graph. Wrapping it as a chat agent would route requests around precisely the components that make an answer trustworthy, and you would get a fluent assistant instead of a validated result.

The dialogue with humans happens in two places instead, both file-shaped and both auditable:

• before a run, through a mandate file (what should be considered), and
• after a run, through a verdict file (what a qualified person decided).

If you want an interactive front end, build it on top of POST /invocations — but keep the verdict step human. An approval loop that a model can close by itself is not an approval loop.

---

2. Who does what

The package has three distinct audiences. Only the first one is technical.

Role	What they do	Where it is documented
Platform operator	Installs the package, sets two environment variables, starts the service, verifies with the offline preflight. One-time work.	This document, sections 3–6.
Ordering domain expert (bestiller)	Writes the mandate file: the objective, which approaches are worth trying, and why. The why is the part the system cannot read out of cost figures.	docs/bestille-en-kjoring.md
Reviewing domain expert (fagperson)	Receives a validated proposal and answers approved or rejected with a written rationale. That verdict is what the system learns from.	docs/ekspert-svar.md

The ordering expert steers what is considered, never what is approved. If you ask for something the numbers do not support, the deterministic validator rejects it and the rejection comes back with its reason. That property is the point of the whole design; do not build around it.

---

3. The process, end to end

1. Prepare a knowledge base for the project — cost documents, technical sources, prior experience — as a document bundle. A working five-document example ships in shared/examples/bygg-energi-mikro, and docs/knowledge-base-recipe.md describes how to build your own.
2. Order a run with a mandate file (optional but recommended). See docs/bestille-en-kjoring.md.
3. Run it — from the CLI, or by POST /invocations against the running service (section 6). The run navigates the knowledge base, debates candidate measures, validates the numbers against the project's actual cost baseline, and returns either a validated proposal or a rejection with a reason. A rejection is a successful run: the negative outcome belongs to the answer, not to the transport, and the API returns HTTP 200 for it.
4. A domain expert judges the outcome and writes a verdict — either inline during the run, or as a JSON file dropped into an inbox directory afterwards, possibly days later. See docs/ekspert-svar.md.
5. Approved verdicts can be promoted into the knowledge base, so the next run reads them as context and does not re-propose something the organisation has already rejected. Promotion is gated: only an approved verdict can be promoted, and raw agent output never enters the knowledge base on its own.

Steps 4 and 5 are what make this a learning loop rather than a report generator.

---

4. Prerequisites in your own tenant

You need, in Microsoft Foundry:

1. A Foundry resource with project management enabled and a project inside it. A Foundry project is required — an Azure OpenAI resource (kind: OpenAI) is a different client surface and will not work.
2. At least one model deployment (any current chat model; a small one is enough).
3. The Foundry User role (role definition id 53ca6127-db72-4b80-b1b0-d745d6d5456d) for the identity that will run it, assigned at project scope. Azure Owner and Contributor grant management permissions only, not the data-plane permissions this needs.

---

5. Configuration — the two variables that matter

5.1 The project endpoint. Resolved as the first non-empty of:

PORTFOLIO_FOUNDRY_PROJECT_ENDPOINT     # yours; wins if set
FOUNDRY_PROJECT_ENDPOINT               # injected by the Foundry hosting platform

Where something injects the second one for you — the Foundry hosting platform does — you need to set nothing. Everywhere else (a laptop, a pipeline, your own runtime) set the first. The value looks like https://<resource>.services.ai.azure.com/api/projects/<project>.

5.2 The model map — this is the one that catches people. The packaged src/portfolio_optimiser/data/model_map.json ships placeholders:

"azure": { "default": "REPLACE-WITH-FOUNDRY-DEPLOYMENT", ... }

Deployment names are tenant-specific, so they are deliberately never committed. The code fail-fasts on a REPLACE-WITH- value rather than guessing. Point PORTFOLIO_MODEL_MAP at your own file:

{
  "local":  { "default": "qwen3:4b",     "proposer": "qwen3:4b",     "checker": "qwen3:4b" },
  "azure":  { "default": "my-deployment", "proposer": "my-deployment", "checker": "my-deployment" }
}

export PORTFOLIO_MODEL_MAP=/path/to/model_map.json

If you skip this, the service starts and answers /readiness — and fails every invocation. That is the single most likely first-deployment failure, which is why it has its own section.

5.3 Verify before you pay for a model call:

uv run python -m portfolio_optimiser.preflight --profile azure

Exit code 0 means every offline-checkable precondition holds: endpoint shape, model-map structure, no placeholders left. It is necessary but not sufficient — RBAC (403), token or tenant problems (401) and a well-formed but non-existent deployment (404) can only surface at the live call.

---

6. Running it

This package is Python and nothing else. There is no image to build and no platform-specific deployment manifest — that was removed deliberately after an external trial, because it forced a container toolchain on receivers who only needed to run the code. How the process is supervised, packaged or placed in your environment is your decision, and this package does not pre-empt it.

Install the locked environment and start the service:

uv sync --frozen --no-dev
uv run python main.py

uv sync --frozen installs the exact resolution every measurement in this repository ran against — never a fresh resolve, which picks other versions. Two dependencies are git-tag-pinned direct references, so git must be on PATH for the install to work.

main.py serves port 8088 (override with PORT), answers GET /readiness, accepts POST /invocations, and exits cleanly on SIGTERM. For a single run without the service, the CLI is the same code path:

uv run portfolio-optimiser --help

The invocations payload is whitelisted against the run signature — unknown fields are refused by name with HTTP 400, never silently ignored:

Field	Required	Notes
project_id	yes	The project to analyse.
docs_dir	yes	Source documents.
verdict_input	yes	The expert verdict for this run.
bundle_dir	no	Knowledge base to navigate.
profile	no	Defaults to azure on this HTTP surface.
max_rounds	no	Debate round cap.
max_tokens	no	Per-invocation token ceiling. Set it. The built-in default is 100 000 tokens per run, which is a ceiling nobody chose for your workload.
top_k	no	Retrieval breadth.

HTTP 400 means the request was malformed; 500 means the run itself failed, with error_type and error in the body. A rejected proposal is 200 — see section 3.

429 is not a failure. It means the run reached its own allowance — the round cap or the token cap — and stopped, which is the cap doing its job rather than anything breaking. The body carries the ledger's own numbers, so you can tell which cap bound and how far past it the run got:

{"budget_exhausted": {"kind": "rounds", "limit": 12, "observed": 13},
 "error": "budget exceeded: rounds limit=12 observed=13"}

There is no error_type (nothing failed) and no Retry-After (waiting changes nothing). Retrying the same body hits the same cap; the remedies are raising max_rounds/max_tokens for that invocation, or accepting that this project did not resolve within the allowance you set.

---

7. Honest limits

• This framework has never been run against a live model in our environment. Everything above is measured against tests and an offline simulation. The first live run in your tenant is the first live run, full stop.
• The system is a technical framework. Data protection assessments, lawful basis and risk ownership belong to whoever deploys it — see README.md and SECURITY.md.
• Readiness does not respond during CPU-bound stretches of a run (the optimisation solve).
• Chunked request bodies are not supported.
• Verdict promotion writes to the knowledge base non-atomically; it assumes a single writing process.