framework · diff

git:20260828.a543672 to git:20260831.d66fd7e

5 added, 49 removed. Audit C to C.

# Framework Agent — Sibling Skill

> **Purpose**: vllm/sglang source-layer optimisation companion for

> `inference_optimizer`. It discovers framework / ref candidates

> (via Primus Cortex + GitHub Search), optionally builds/benchmarks

> them in isolated worktrees, and serves the Coordinator's

> FRAMEWORK_AGENT phase. Exposed through the `fa` / `framework-agent`

> console entry points.

## Layout

This skill lives in the `hyperloom` src-layout distribution:

```

src/hyperloom/agents/framework/ # hyperloom.agents.framework

- ├── runtime/cli.py # fa schema / candidates / explore / phase-discover / kb

+ ├── runtime/cli.py # fa schema / candidates / explore / kb

├── runtime/tools_api.py # library API behind the CLI verbs

├── explorer.py # explore loop (libcst-free)

├── isolation.py # per-candidate worktree + venv

├── decision.py # 3-gate winner decision

├── kb.py # knowledge-base operations

├── repo_map.py # framework -> canonical repo URL

├── keywords.py / models.py # request models + keyword helpers

├── logging_setup.py # shared: structured logging

├── sources/ # primus_cortex + github discovery

└── tests/

```

The `fa` CLI ships with the distribution, so there is no separate installer

for this skill: `pip install -e '.[test]'` from the repo root provides it.

The KB a session reads and writes is `INFERENCE_OPTIMIZER_FA_KB_PATH` when

set, else `<workspace>/framework-kb` (`USER_DATA_PATH` or the pod-local

default). It is deliberately not `<workspace>/kb`, the legacy recipe root:

every directory under this root is reported as a framework domain. The

orchestrator's writeback resolves the same root, so both halves move together.

The runtime partition written under it is `framework_optimization/<framework>/`.

Read-only seed data shipped in the wheel lives separately under the package.

## Subcommands

```bash

fa schema # print the request schema summary (debug)

fa candidates --request req.json [--out -] # enumerate PR/ref candidates, no build/bench

fa explore --request req.json [--execute] [--out -] # plan (default) or build/bench loop

- fa phase-discover --request req.json [--out -] # Coordinator FRAMEWORK_AGENT phase entry point

- fa phase-audit --request req.json [--out -] # static local-source judging of a discovered candidate

fa kb list|show|search|contribute|synthesize ... # knowledge-base ops

```

`fa candidates` / `fa explore` run a standalone investigation loop (no

- IO coordinator). The `fa phase-*` subcommands were the Coordinator's own

- entry points into this agent; the Coordinator no longer invokes them —

- candidate discovery is a specialist, and its verdicts arrive in the

- deliverable rather than from a per-candidate audit call.

- ## FRAMEWORK_AGENT phase (`fa phase-discover`)

- Reads `--request <json>` and writes `--out <json|->` (envelope style

- mirrors `hyperloom.agents.critic.runtime.cli`):

- ```bash

- # Discover a batch of PR candidates for the current run's gaps.

- # request: {model, framework, gpu_type, gaps[], repo_url?, max_search_candidates, batch_id}

- # output: {batch_id, framework, repo_url, candidates: [...]}

- fa phase-discover --request req.json --out -

- ```

- ## FRAMEWORK semantic audit (`fa phase-audit`)

- Given a discovered candidate + the live framework source roots, decide whether

- the PR's change is already present locally so the Coordinator can skip

- already-merged PRs and seed the authoring specialist with evidence:

- ```bash

- # request: {candidate, framework, framework_source_roots[],

- # diff_text|patches_path|primus_cortex_url, work_dir?, use_llm?, model?}

- # output: {candidate_id, semantic_status, applicability, confidence,

- # evidence[], risks[], recommended_next_step, layer, metrics}

- fa phase-audit --request req.json --out -

- ```

- - **static layer (default, hermetic)**: parse the diff, resolve each touched

- file under `framework_source_roots`, measure added-line / symbol presence +

- context-anchor presence.

- - `semantic_status` ∈ `already_equivalent` / `already_superset` /

- `partially_present` / `not_present` / `unknown`.

- - `applicability` ∈ `direct_apply` / `needs_rewrite` / `not_applicable` /

- `needs_human_review`; `recommended_next_step` ∈ `skip` /

- `direct_framework` / `author_via_specialist`.

- - `already_*` is evidence-gated (downgraded to `unknown` without a concrete

- symbol/line hit).

- - **llm layer (opt-in, `use_llm=true`)**: single chat-completion refine; needs

- `OPENAI_API_KEY` + `OPENAI_BASE_URL`; best-effort; never authors patches.

+ IO coordinator). This agent has no Coordinator entry point: candidate

+ discovery is a specialist, and its verdicts arrive in the deliverable rather

+ than from a per-candidate audit call.

## Candidate refs feed the targeted build

A discovered candidate reference now drives the enablement targeted build

(compiled-component acquisition), not just the git-apply/bench path:

- A candidate is resolved to a checkoutable ref — a PR reference becomes that

PR's head ref — so support that only exists in an unreleased PR/branch is

reachable, not just released-tag autoselect.

- The source PR URL is recorded as build provenance and surfaces in the session

breakdown's `build_attempts[].installed_versions` as `source_pr_url`.

## Enablement ladder (methodology)

When a candidate is for enablement (making a `(model, backend)` combo that is

non-runnable, or boots but fails its accuracy eval, run correctly — not perf),

the repair follows a tiered ladder — diagnose the

missing capability layer once, then climb only as far as needed: Rung 0

diagnose, 1 serve-flag/config wire-up, 2 in-tree source patch, 3 attempt-scoped

runtime, 4 source localization, 5 off-loop compiled build. A supported-but-un-wired

model needs only the cheap top rungs; a genuinely-new architecture climbs higher.

The canonical rendered text is `build_enablement_ladder_book` in

`hyperloom.agents.framework.enablement_ops` (injected into the enablement

authoring specialist's prompt); see also `docs/conceptual/optimization-loop.md`

("Enablement escalation ladder").

## KB partition (`fa kb`)

Read priors before generating a patch; write lessons only after a KEEP

verdict. Operations all live under the `framework_optimization` domain:

```bash

fa kb list # list available KB domains

fa kb show --domain framework_optimization # show files in a domain

fa kb search --query "chunked prefill" # case-insensitive content search

fa kb contribute --domain framework_optimization --body-file finding.md

fa kb synthesize --domain framework_optimization --findings findings.json [--with-llm]

```

`contribute` appends to `${KB}/<domain>/empirical_kb.md`, creating the domain

- dir and file if missing. The `framework_optimization` partition already exists

- in a fresh install — it ships `cross_framework_map.jsonl` (package data) as its

- only seed.

+ dir and file if missing. The `framework_optimization` partition is created on first contribution.