feat: run engram on openai gpt-5 models and the flex tier

[Barsoomx]

Makes Engram usable on OpenAI gpt-5.x models and on OpenAI's cheaper flex service tier, so the curation pipeline can run without DeepSeek.

Why

The stand's pipeline has been dead since 2026-07-23 (DeepSeek 402). Moving to OpenAI is cheaper than topping up: measured on real traffic volumes, gpt-5-nano + gpt-5-mini cost ~$16/10d against DeepSeek's $170, and flex halves that again.

The current gateway could not talk to gpt-5.x at all. Verified by live calls against api.openai.com on 2026-07-27:

'max_tokens'         -> 400 "use 'max_completion_tokens'"
'temperature': 0.2   -> 400 "only the default (1) value is supported"
'service_tier':'flex'-> OK, response echoes service_tier="flex"

What changed

Request shaping. ModelPolicy.metadata['request_shape'] declares how a model family wants its request spelled: which completion-token parameter, whether temperature is sent, and per-response-kind reasoning_effort. Derived automatically from the model name — presets and hand-created policies both get it, and switching a policy's model re-derives it (and drops service_tier if the new family has no flex).

Flex tier. service_tier is now actually sent, with the socket sized to the tier. Escalation is by attempt count, not error kind: our classifier maps flex-capacity 429 and ordinary rate-limit 429 to the same code, so they are indistinguishable — late attempts fall back to the project default so work lands instead of being lost.

Flex is opt-in on both layers. A policy asks for flex; the deployment must also declare ENGRAM_FLEX_TIMEOUT_SIZING=1 before any ladder grows. Without it, applying the flex preset is refused with a message telling you what to set. This keeps zero drift for everyone else — verified value-by-value against master:

	master	branch, no opt-in
observation	60/90, lease 120s	identical
session_distillation	600/660, lease 720s	identical
candidate_decision	240/270, lease 300s	identical
digest / embedding	180/210	identical

Presets. openai_all now names gpt-5-nano/gpt-5-mini instead of gpt-5.4/gpt-5.4-mini — the old pair measured 4.7× more expensive than the DeepSeek setup it replaces. A new openai_all_flex preset adds the flex tier. Every OpenAI preset now ships pricing, without which cost_usd records 0.0000 and spend becomes unauditable.

Verification

Full backend suite: 3508 passed.

End-to-end against the real API, through the real gateway and a preset-created policy:

standard : {"model":"gpt-5-mini","max_completion_tokens":8192,"reasoning_effort":"minimal"}
           socket 60s   cost_usd 0.000035
flex     : {... ,"service_tier":"flex"}
           socket 600s  cost_usd 0.000018

Both real calls returned 200. No max_tokens, no temperature. Cost is exact and halves on flex.

The strict curation_decision_v1 schema was also probed against both models with the real 4432-char prompt prefix — both return valid verdicts.

Known gaps

• attempt is threaded from 4 of 7 ProviderCallInput sites; the realtime candidate path and on-demand digest have no WorkflowWork in scope, so they never escalate off flex.
• No data migration: pre-existing gpt-5 policy rows keep their old metadata until updated or replaced by a preset.
• On effort=low, gpt-5-nano spends more output than gpt-5-mini (1311 vs 622 tokens) — smaller model, more reasoning. Presets pin minimal.

🤖 Generated with Claude Code

[Barsoomx]

✅ Snyk checks have passed. No issues have been found so far.

Status	Scan Engine	Critical	High	Medium	Low	Total (0)
✅	Open Source Security	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.

[codecov-commenter]

Codecov Report

❌ Patch coverage is 99.51220% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 91.03%. Comparing base (599e7dc) to head (f403e51).
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
apps/backend/engram/model_policy/services.py	99.18%	1 Missing ⚠️
apps/backend/engram/model_policy/validation.py	97.05%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #299      +/-   ##
==========================================
+ Coverage   90.89%   91.03%   +0.13%     
==========================================
  Files         218      221       +3     
  Lines       22722    23099     +377     
==========================================
+ Hits        20654    21029     +375     
- Misses       2068     2070       +2     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

[codecov-commenter]

Bundle Report

Bundle size has no change ✅

Affected Assets, Files, and Routes:

view changes for bundle: engram-frontend-client-array-push

Assets Changed:

Asset Name	Size Change	Total Size	Change (%)
static/MRkPl1J45MFa7Bf0X0IkW/_buildManifest.js (New)	1.51kB	1.51kB	100.0% 🚀
static/MRkPl1J45MFa7Bf0X0IkW/_ssgManifest.js (New)	77 bytes	77 bytes	100.0% 🚀
static/Di60FX5fkVc0T-*.js (Deleted)	-77 bytes	0 bytes	-100.0% 🗑️
static/Di60FX5fkVc0T-*.js (Deleted)	-1.51kB	0 bytes	-100.0% 🗑️