> For the complete documentation index, see [llms.txt](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/sessions/phase40-session09-model-intelligence-and-pricing/spec.md).

# Session Specification

**Session ID**: `phase40-session09-model-intelligence-and-pricing` **Phase**: 40 - Claude OS v2.10.1 Semantic Port **Status**: Not Started **Created**: 2026-07-03 **Base Commit**: 925db249efec9b21eb95479415966d7b8586f5eb

***

## 1. Session Overview

This session adds the Hermes-scoped Ministry model intelligence and pricing contract required by the Phase 40 plan. It keeps the data inside Hermes bridge, hook, parser, and fixture owners instead of introducing a repo-level `src/data/model-intel.json` file.

The session is next because Session 08 completed the bundled model catalog, provider presentation metadata, context fallbacks, safe demo fixtures, and Pantheon model option coverage. Session 09 builds on that contract by adding a small Ministry lineup with benchmark, cost, speed, missing-metric fallback, and pricing provenance semantics.

The live pricing overlay is local-only and opportunistic. The app may fetch the public OpenRouter model list without a key from local live mode, but public demo mode remains fixture-only, benchmark data remains bundled/static, and any live price failure falls back to the bundled snapshot with explicit provenance.

***

## 2. Objectives

1. Add a Hermes-scoped Ministry model intelligence subset for Claude Opus 4.8, GPT-5.5, GLM 5.2, and DeepSeek V4 Pro.
2. Add bundled snapshot pricing plus optional keyless local OpenRouter pricing overlay with 30-minute stale-time semantics.
3. Expose browser-safe parser and hook contracts for Ministry model ranking by benchmark, cost, and speed without live benchmark claims.
4. Add focused tests for default lineup availability, stable ranking, live-price fallback, demo-disabled live pricing, and missing-metric fallbacks.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase40-session08-catalog-and-context-metadata` - Provides the bundled Hermes catalog provenance, provider labels, context metadata, alias-aware filtering, safe demo fixtures, and Pantheon model option baseline.

### Required Tools Or Knowledge

* Bun 1.3.14 and existing Vitest, TypeScript, lint, and Prettier tooling.
* Existing Hermes bridge, parser, hook, demo fixture, and test patterns.
* OpenRouter public model-list response shape enough to parse pricing without a key.

### Environment Requirements

* No required credentials. Live OpenRouter pricing is optional and must degrade to bundled snapshot pricing when network access fails.
* No app database, migrations, ORM, seed data, or DB verification are required.

***

## 4. Scope

### In Scope (MVP)

* Hermes users can read a browser-safe Ministry model intelligence body through the local Hermes bridge - Implemented as a Hermes-scoped contract and helper, not a global model intelligence data file.
* Hermes users can distinguish bundled snapshot pricing from live OpenRouter pricing - Implemented with explicit per-row and body-level provenance.
* Hermes Ministry analytics can rank the default lineup by benchmark, cost, and speed - Implemented with deterministic ranking helpers and missing-metric fallback semantics.
* Public demo users see fixture-only model intelligence - Implemented through demo fixtures and hook/page plumbing that never fetches live pricing in demo mode.
* Developers can validate default lineup rows, parser behavior, pricing fallback, live overlay failure, and stable sorting - Implemented through focused tests near the changed owners.

### Out Of Scope (Deferred)

* Repo-wide `src/data/model-intel.json` - Reason: the Phase 40 stub explicitly keeps this subset Hermes-scoped.
* Live benchmark data - Reason: the session must not claim live benchmark data; benchmarks are bundled/static model intelligence fields only.
* Fetching live pricing in public/demo mode - Reason: public demo must remain fixture-only and static.
* Full Ministry builder, Pantheon integration, MoA config analytics, and save UX
  * Reason: Sessions 14 and 15 own those product workflows.
* Provider-authenticated OpenRouter account reads - Reason: this session uses public model-list data only and must not require or expose credentials.

***

## 5. Technical Approach

### Architecture

Add a script-side Hermes model intelligence owner under `scripts/lib/` for the default lineup rows, bundled pricing snapshot, OpenRouter pricing parser, and local-live overlay resolver. Wire that owner into `scripts/lib/hermes-dev-bridge.ts` through a new public local read endpoint that preserves existing loopback, Host-header, method, no-store, and safe-error behavior.

Add browser contract types and parsers in `src/lib/hermes-types.ts`, plus a small `src/lib/hermes-model-intelligence.ts` helper for stable ranking by benchmark, cost, and speed. `useHermes` should expose the parsed body with explicit loading, empty, error, offline, and demo-safe states, while public demo fixtures remain bundled snapshot only.

### Design Patterns

* Parser-owned contracts: Keep bridge payload validation in `src/lib/hermes-types.ts` so components and hooks never consume raw response shapes.
* Script-side local bridge ownership: Keep local network fetch and pricing fallback logic in `scripts/lib/`, matching existing Hermes bridge behavior.
* Fixture-first demo boundary: Keep public/demo data in `src/lib/hermes-demo-data.ts` and avoid any live `/__*` or third-party pricing fetch in demo mode.
* Deterministic ranking: Sort by requested metric, then missing-metric fallback, then stable model identity so analytics do not drift across runs.

***

## 6. Deliverables

### Files To Create

| File                                                      | Purpose                                                                                                                         | Est. Lines |
| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `scripts/lib/hermes-model-intelligence.ts`                | Hermes-scoped Ministry rows, bundled pricing snapshot, OpenRouter pricing parser, live overlay resolver, and provenance helpers | \~260      |
| `scripts/lib/__tests__/hermes-model-intelligence.test.ts` | Unit tests for default lineup, pricing parser, cache/fallback behavior, and no-secret output                                    | \~220      |
| `src/lib/hermes-model-intelligence.ts`                    | Browser-safe Ministry ranking helpers for benchmark, cost, speed, and missing metrics                                           | \~140      |
| `src/lib/__tests__/hermes-model-intelligence.test.ts`     | Unit tests for stable ranking and missing-metric fallback behavior                                                              | \~160      |

### Files To Modify

| File                                                       | Changes                                                                                              | Est. Lines |
| ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ---------- |
| `scripts/lib/hermes-dev-bridge.ts`                         | Register and implement `/__hermes_model_intelligence` using the script-side model intelligence owner | \~90       |
| `scripts/lib/__tests__/hermes-dev-bridge.test.ts`          | Add endpoint registration, success, fallback, and sanitized output coverage                          | \~160      |
| `src/lib/hermes-types.ts`                                  | Add model intelligence, pricing provenance, parser, and query-view contract types                    | \~170      |
| `src/lib/__tests__/hermes-types.test.ts`                   | Add parser validation and demo fixture alignment coverage                                            | \~150      |
| `src/lib/hermes-demo-data.ts`                              | Add bundled-snapshot demo model intelligence fixture with live pricing disabled                      | \~90       |
| `src/hooks/use-hermes.ts`                                  | Add query key, fetch, stale time, empty-state mapping, and result exposure                           | \~80       |
| `src/hooks/__tests__/use-hermes.test.tsx`                  | Add hook fetch, no-token, stale-time, demo-disabled, and error-state coverage                        | \~140      |
| `src/components/hermes/hermes-read-only-page.tsx`          | Thread demo/live model intelligence view only where needed for existing Hermes data plumbing         | \~40       |
| `src/components/hermes/__tests__/hermes-sections.test.tsx` | Keep Hermes mocks and demo fixture expectations aligned with the expanded hook result                | \~80       |

***

## 7. Success Criteria

### Functional Requirements

* [ ] Hermes exposes a browser-safe model intelligence response with the default Ministry lineup rows for Claude Opus 4.8, GPT-5.5, GLM 5.2, and DeepSeek V4 Pro.
* [ ] Ranking helpers can rank by benchmark, cost, and speed with deterministic tie-breakers and missing-metric fallbacks.
* [ ] Live OpenRouter pricing is used only when returned by the local live overlay and is labeled as live OpenRouter data.
* [ ] Bundled snapshot pricing is used when live pricing is disabled, missing, stale, malformed, timed out, or failed.
* [ ] Public/demo mode uses bundled fixture data and does not fetch live OpenRouter pricing.
* [ ] Analytics do not claim live benchmark data.

### Testing Requirements

* [ ] Script-side model intelligence tests pass.
* [ ] Hermes bridge tests cover the new endpoint and failure fallback paths.
* [ ] Browser parser, fixture, ranking helper, and hook tests pass.
* [ ] Focused Vitest command passes for all changed Hermes model-intelligence test files.

### Non-Functional Requirements

* [ ] OpenRouter fetches are bounded by timeout, retry/backoff, 30-minute stale time, and snapshot fallback.
* [ ] Browser-visible output contains no provider keys, raw auth JSON, local paths, bearer tokens, prompts, transcripts, or raw private payloads.
* [ ] Public demo remains fixture-only and static.

### Quality Gates

* [ ] All files ASCII-encoded.
* [ ] Unix LF line endings.
* [ ] Code follows project conventions.
* [ ] No new global `findtrend` identifiers.
* [ ] No repo-level `src/data/model-intel.json` is added.

***

## 8. Implementation Notes

### Working Assumptions

* A dedicated `/__hermes_model_intelligence` read endpoint is the safest contract boundary for Session 09: the stub requires Hermes-scoped Ministry model rows and pricing provenance, while existing code keeps Hermes reads in `scripts/lib/hermes-dev-bridge.ts`, browser parsing in `src/lib/hermes-types.ts`, and hook exposure in `src/hooks/use-hermes.ts`. Planning can proceed because this follows the Session 08 bridge/parser/hook pattern and does not require a repo-wide data file.
* The session can add data plumbing without building the final Ministry analytics UI: Phase 40 assigns Pantheon/Ministry builder and analytics UX to Sessions 14 and 15, while Session 09 owns the durable rows, pricing provenance, and ranking inputs those later sessions need.

### Key Considerations

* Keep upstream ports semantic, not wholesale; do not copy upstream monolithic route or Vite middleware files.
* Preserve local control-plane gates, safe errors, and no raw private output for the new Hermes read path.
* Treat OpenRouter as an optional public pricing source only; do not require keys or expose account-auth data.
* Keep public demo behavior fixture-only.

### Potential Challenges

* OpenRouter response drift: Parse only needed public fields, validate numbers, and fall back to bundled snapshot pricing on malformed or missing data.
* Pricing cache drift: Use a 30-minute stale time with deterministic fallback provenance and tests that inject time/fetch behavior.
* Missing metrics: Provide explicit fallback state and ranking tie-breakers so analytics stay stable without showing `unknown` gaps for required default rows.
* Hook result expansion: Update component test mocks and demo fixture plumbing so TypeScript and current UI tests remain aligned.

### Relevant Considerations

* \[P38] **Upstream ports are semantic, not wholesale**: Map upstream model intelligence and pricing behavior into AI OS Hermes owners instead of copying upstream files.
* \[P38] **Local control-plane gates are defense in depth**: Preserve loopback, Host-header, method, timeout, schema, and safe-error behavior for the new public local read.
* \[P31-P39] **Public-demo, AI Rogue, and hosted-surface gates stay bundled**: Keep demo model intelligence fixture-only and avoid public live pricing.
* \[P00] **Stack conventions**: Use Bun, TypeScript, React Query, and existing local test placement patterns.

### Behavioral Quality Focus

Checklist active: Yes

Top behavioral risks for this session:

* Live pricing fetches can hang, fail, or return malformed data; tasks include timeout, retry/backoff, cache, fallback, and explicit provenance handling.
* Demo/public mode can accidentally become live; tasks include demo fixture and hook gating coverage.
* Analytics can drift or mislead when fields are missing; tasks include parser, fallback, no-live-benchmark claims, and deterministic ranking coverage.

***

## 9. Testing Strategy

### Unit Tests

* Test `scripts/lib/hermes-model-intelligence.ts` default lineup coverage, OpenRouter price parsing, bounded values, cache behavior, timeout/failure fallback, and sanitized output.
* Test `src/lib/hermes-model-intelligence.ts` ranking by benchmark, cost, speed, and missing metrics with stable tie-breakers.
* Test `parseHermesModelIntelligenceResponse` valid and invalid shapes, provenance labels, demo fixture alignment, and no-live-benchmark semantics.

### Integration Tests

* Extend `scripts/lib/__tests__/hermes-dev-bridge.test.ts` for route registration, local live overlay success, OpenRouter failure fallback, and no-token public read behavior.
* Extend `src/hooks/__tests__/use-hermes.test.tsx` for query fetch, stale time, no sensitive token header, offline/error states, and demo-disabled live pricing.

### Runtime Verification

* Run focused Vitest for model intelligence, Hermes bridge, parser, hook, and Hermes section tests.
* Run `bun run typecheck`, `bun run typecheck:scripts`, and `bun run lint`.

### Edge Cases

* OpenRouter fetch unavailable, timed out, malformed, or missing a default lineup model.
* Price fields present as strings, nulls, zeros, or invalid negative values.
* Models missing benchmark, speed, or pricing fields.
* Public demo mode and offline mode.
* Unknown provider aliases and configured catalog subsets.

***

## 10. Dependencies

### Other Sessions

* Depends on: `phase40-session08-catalog-and-context-metadata`
* Depended by: `phase40-session14-ministry-builder-and-pantheon`, `phase40-session15-ministry-config-analytics-and-save-ux`, `phase40-session18-full-validation-and-handoff`

***

## Next Steps

Run the `implement` workflow step to begin implementation.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/sessions/phase40-session09-model-intelligence-and-pricing/spec.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.