Managing Applications¶

An Application is the unit you manage: one upstream LLM with G1-Hummingbird in the middle, owning its own policy (nine thresholds + enforcement modes), knowledge base, cost centre, compliance posture and API keys. One deployment serves many, isolated from each other, on shared hardware.

Call it¶

What it does. Creates the Application, writes its policy, and mints the key it will authenticate with. Read /apps/meta first — it reports the axes the served detector actually has, and a policy naming any other axis is rejected with a 400.

BASE=http://localhost:8080; J='-H Content-Type:application/json'

curl -s $BASE/v1/glad/apps/meta | jq '.axes'

APP=$(curl -s $BASE/v1/glad/apps $J -d '{
  "name":"Support Bot",
  "config":{"binding":{"upstream_type":"ollama",
                       "base_url":"http://localhost:11434","model":"llama3.1:8b"}}
}' | jq -r .app_id)

curl -s -X PUT $BASE/v1/glad/apps/$APP/policy $J -d '{
  "policy":{"thresholds":{"prompt_safety":0.80},
            "enforcement":{"answer_safety":"block"},
            "scope":"Answers questions about our travel booking service."}
}' | jq '.config_version'

curl -s $BASE/v1/glad/apps/$APP/keys $J -d '{"role":"invoke"}' | jq -r .api_key

import httpx

c = httpx.Client(base_url="http://localhost:8080", timeout=60)
# If a platform token is configured:
# c.headers["X-Geodesia-Admin-Key"] = os.environ["GEODESIA_ADMIN_TOKEN"]

meta = c.get("/v1/glad/apps/meta").json()
print("axes on this deployment:", meta["axes"])

app = c.post("/v1/glad/apps", json={
    "name": "Support Bot",
    "config": {"binding": {"upstream_type": "ollama",
                           "base_url": "http://localhost:11434",
                           "model": "llama3.1:8b"}},
}).json()
app_id = app["app_id"]

c.put(f"/v1/glad/apps/{app_id}/policy", json={"policy": {
    "thresholds": {"prompt_safety": 0.80},
    "enforcement": {"answer_safety": "block"},
    # out_of_scope stays silent until something declares the scope
    "scope": "Answers questions about our travel booking service.",
}})

key = c.post(f"/v1/glad/apps/{app_id}/keys", json={"role": "invoke"}).json()
print(key["api_key"])        # returned ONCE

const BASE = "http://localhost:8080"
const H = { "Content-Type": "application/json" }

const meta = await fetch(`${BASE}/v1/glad/apps/meta`).then(r => r.json())

const app = await fetch(`${BASE}/v1/glad/apps`, {
  method: "POST", headers: H,
  body: JSON.stringify({ name: "Support Bot",
    config: { binding: { upstream_type: "ollama",
                         base_url: "http://localhost:11434", model: "llama3.1:8b" } } }),
}).then(r => r.json())

await fetch(`${BASE}/v1/glad/apps/${app.app_id}/policy`, {
  method: "PUT", headers: H,
  body: JSON.stringify({ policy: { thresholds: { prompt_safety: 0.80 },
                                   scope: "Answers questions about our travel booking service." } }),
})

const key = await fetch(`${BASE}/v1/glad/apps/${app.app_id}/keys`, {
  method: "POST", headers: H, body: JSON.stringify({ role: "invoke" }),
}).then(r => r.json())

What comes back — {app_id, config_version, status, app: {…}} from the create, the merged policy plus a bumped config_version from the PUT, and from the key call an api_key shown only once: only its hash is stored.

Field-by-field request/response reference: Control Plane API.

Creating an Application from the UI¶

Open Applications (ApplicationsView) and click New Application to open the creation modal. The modal performs live model discovery against the upstream you choose, so you pick a real model instead of typing one:

Discovery is served by the control-plane endpoint POST /v1/glad/apps/upstream/models, which returns the model list and its source (or an error you can act on).

In the same modal you set the cost for the Application — €/Mtok for input and output tokens — so the cost center is configured from the start.

Once created, the Application opens to its detail view, organised into tabs:

Saving any tab validates the full AppConfig, bumps config_version, and takes effect on the next request.

Read-only Overview, then edit with auto-save¶

The detail view opens on a read-only Overview tab — a safe summary of the Application's binding, policy, cost, and governance that you can't change by accident. To make changes, click Modifica, which switches to the editable settings tabs: Model, Policy, Cost & Budget, Governance, and API Keys.

There is no "Save" button. Every change in those tabs is saved automatically, debounced shortly after you stop editing — adjust a threshold slider, change the budget, edit alert_recipients, and it persists on its own. An inline status indicator shows where each edit stands: "Saving…" while the debounced write is in flight, then "Saved ✓" once it lands (and the underlying config_version bumps). Because saving is automatic, dependent UI — such as the Cost & Budget projection chart — redraws immediately against the new values.

The Model tab: discover and test¶

The editable Model tab (under Modifica) does more than hold the binding fields — it lets you bind to a real upstream model with confidence:

• Live model discovery. The Model field is an input backed by a datalist, so you can pick a discovered model or type your own. Models are discovered from the chosen upstream — Ollama (/api/tags), vLLM / OpenAI-compatible (/v1/models), or the curated Bedrock / Vertex catalogs — via POST /v1/glad/apps/upstream/models. Discovery runs automatically and debounced whenever you change the upstream type or the base URL (so a URL typed character-by-character only fires one query when you pause), and a ↻ discover button re-runs it on demand. An inline hint shows how many models were found, the source, or an actionable error if the upstream couldn't be listed.

• Test connection. A Test connection button probes the bound upstream for reachability (with a latency reading) and runs a logprob probe that reports whether the closed-book axis is available or unavailable for that model — since halluc_closedbook depends on per-token log-probabilities. A reachable upstream also refreshes the discovered-model list.

Where each setting lives: Applications vs. Settings¶

Studio splits configuration cleanly between the per-Application detail view and the platform-wide Settings page:

Configuration model¶

Each Application stores a validated AppConfig JSON document (config_json), versioned by config_version (incremented on every config update). The document has five sections — binding, complex_routing, policy, cost, governance — plus two top-level fields. Missing axes are always back-filled with the defaults, so the axis contract always holds downstream.

binding — the upstream LLM¶

Allowed upstream_type values: openai, ollama, vllm, sglang, trtllm, bedrock, vertex, azure-openai, internal.

The logprobs setting governs the closed-book fabrication axis: require forces a logprob-capable path, off disables it, and auto (default) uses logprobs when the upstream offers them. See Detection Axes for why halluc_closedbook depends on per-token log-probabilities.

complex_routing — a second model for hard prompts¶

Optional. Disabled by default, in which case the Application behaves exactly as a single-model deployment and no routing logic runs at all.

See Token & Cost Control for what this buys you and how to size the threshold.

policy — detection thresholds and enforcement¶

The policy is scored across the nine G1-Hummingbird axes. Each axis has its own threshold (probability space, 0.0–1.0) and its own enforcement mode.

Defaults (DEFAULT_THRESHOLDS / DEFAULT_ENFORCEMENT — the serving calibration of the 9-axis head; prompt_safety and jailbreak share a joint 2 % false-positive budget measured on a multilingual benign pool):

The two optional_detectors are off by default: causal_xai adds causal token attribution (see Causal XAI), and self_consistency draws multiple samples to reduce closed-book fabrication false positives.

cost — rates and budget (FinOps)¶

All rate fields must be ≥ 0; alert_pct is rejected if not ascending; on_budget_exceeded must be alert or block. The cost rate is snapshotted at call time so historical costs stay stable when you later change rates.

governance — compliance and oversight¶

Allowed risk_classification values (RISK_CLASSES): minimal, limited, high, unacceptable, unknown.

The human_oversight object controls when a call is auto-escalated for human review: auto_trigger enables it, and safety_threshold / halluc_threshold set the scores above which a call is routed to the oversight queue. See Human Oversight and FRIA.

Lifecycle states¶

Every Application is in exactly one of three states, stored in the status column:

State transitions go through set_status, which only accepts active, paused, or killed. Pausing and resuming are the same operation with a different target state.

API keys¶

Each Application has its own API keys. A key is the Application's runtime identity on the data plane: an invoke key sent as Authorization: Bearer g1k_live_… on a chat or RAG request now routes that request to its Application and scopes the request's policy, cost, quota, and compliance to it — even when no X-Geodesia-App header or application_id is supplied. (Previously an invoke key was control-plane-only — a read-only credential; it is now also the data-plane routing identity.) An explicit application_id / X-Geodesia-App still wins over the key. See Data-plane routing.

Operations:

• Create — generates a new key, returns the plaintext once along with key_id, app_id, key_preview, and role.
• List — returns key metadata (key_id, key_preview, role, active, created_at, last_used_at, expires_at) for an Application — never the plaintext or the hash.
• Revoke — sets active = 0. Revoked and expired keys fail verification immediately.

A request authenticates by presenting the plaintext key; verification hashes it, looks up the active, unexpired record, touches last_used_at, and resolves it to {app_id, role}. The full create/list/revoke routes are documented in the Control Plane API.

Free-tier limit¶

The number of Applications an Organization may create is capped by its license entitlement (max_applications). On the free tier the cap is one Application, so the New Application button is disabled once the default Application exists — you can still fully configure, key, and operate that one Application.