# sybil-solutions/inference-optimisation-skill architecture

> Architecture diagram of the GitHub repository sybil-solutions/inference-optimisation-skill, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sybil-solutions/inference-optimisation-skill
- Repository: https://github.com/sybil-solutions/inference-optimisation-skill

## Overview

This repository is an agent skill and lightweight harness for optimizing local LLM inference, not an inference server. Its main workflow estimates performance ceilings, benchmarks a baseline, iterates on one tuning lever using interleaved controls, records results, then validates stability and qualifies a pinned build before publishing. The README also describes memory monitoring and engine-specific guidance. Only ceiling.py was excerpted; other module relationships below are limited to capabilities and workflow links explicitly documented in the README.

Main entry points: [`skills/inference-optimisation/SKILL.md`](https://github.com/sybil-solutions/inference-optimisation-skill/blob/main/skills/inference-optimisation/SKILL.md) (Optimization procedure), [`skills/inference-optimisation/scripts/bench.py`](https://github.com/sybil-solutions/inference-optimisation-skill/blob/main/skills/inference-optimisation/scripts/bench.py) (Server benchmark), [`skills/inference-optimisation/examples`](https://github.com/sybil-solutions/inference-optimisation-skill/tree/main/skills/inference-optimisation/examples) (Benchmark configurations), [`skills/inference-optimisation/scripts/queue.sh`](https://github.com/sybil-solutions/inference-optimisation-skill/blob/main/skills/inference-optimisation/scripts/queue.sh) (Serialized run queue)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_guidance["Procedure and guidance"]
  node_skill["Optimization procedure<br/>[SKILL.md]"]
  node_task_prompt["Agent task prompt<br/>[PROMPT.md]"]
  node_ceiling_guidance["Ceiling methodology<br/>[ceilings.md]"]
  node_measurement_guidance["Measurement methodology<br/>[methodology.md]"]
  node_tuning_guidance["Tuning levers<br/>[levers.md]"]
  node_engine_guidance["Engine gotchas<br/>[gotchas.md]"]
  node_publishing_guidance["Publishing guidance<br/>[publishing.md]"]
end

subgraph group_measurement["Measurement tools"]
  node_ceiling_tool["Ceiling calculator<br/>[ceiling.py]"]
  node_benchmark["Server benchmark<br/>[bench.py]"]
  node_memory_monitor["Memory monitor<br/>[mem.sh]"]
end

subgraph group_experiments["Experiment workflow"]
  node_examples["Benchmark configurations"]
  node_run_queue["Serialized run queue<br/>[queue.sh]"]
  node_result_ledger[("Result ledger")]
  node_plan["Tuning plan"]
end

subgraph group_qualification["Validation and release"]
  node_needle_gate["Long-context retrieval gate<br/>[bench.py]"]
  node_soak["Full-KV concurrency soak<br/>[SKILL.md]"]
  node_clean_build["Pinned clean build<br/>[publishing.md]"]
  node_acceptance["Acceptance gates<br/>[publishing.md]"]
  node_published_results["Published results<br/>[publishing.md]"]
end

node_operator(("Engineer or agent"))
node_local_server["OpenAI-compatible server"]

node_operator -->|"follows procedure"| node_skill
node_operator -->|"uses prompt"| node_task_prompt
node_skill -->|"consults"| node_ceiling_guidance
node_skill -->|"consults"| node_measurement_guidance
node_skill -->|"consults"| node_tuning_guidance
node_skill -->|"consults"| node_engine_guidance
node_skill -->|"consults"| node_publishing_guidance
node_operator -->|"computes ceilings"| node_ceiling_tool
node_examples -->|"provides inputs"| node_ceiling_tool
node_operator -->|"runs benchmark"| node_benchmark
node_examples -->|"configures run"| node_benchmark
node_benchmark -->|"sends requests"| node_local_server
node_benchmark -->|"logs results"| node_result_ledger
node_operator -->|"checks footprint"| node_memory_monitor
node_operator -->|"queues runs"| node_run_queue
node_run_queue -->|"runs controls"| node_benchmark
node_result_ledger -->|"informs tuning"| node_plan
node_plan -->|"guides next change"| node_operator
node_benchmark -->|"checks retrieval"| node_needle_gate
node_needle_gate -->|"precedes soak"| node_soak
node_soak -->|"precedes qualification"| node_clean_build
node_clean_build -->|"runs gates"| node_acceptance
node_acceptance -->|"qualifies results"| node_published_results

click node_skill "https://github.com/sybil-solutions/inference-optimisation-skill/blob/main/skills/inference-optimisation/SKILL.md"
click node_task_prompt "https://github.com/sybil-solutions/inference-optimisation-skill/blob/main/PROMPT.md"
click node_ceiling_guidance "https://github.com/sybil-solutions/inference-optimisation-skill/blob/main/skills/inference-optimisation/references/ceilings.md"
click node_measurement_guidance "https://github.com/sybil-solutions/inference-optimisation-skill/blob/main/skills/inference-optimisation/references/methodology.md"
click node_tuning_guidance "https://github.com/sybil-solutions/inference-optimisation-skill/blob/main/skills/inference-optimisation/references/levers.md"
click node_engine_guidance "https://github.com/sybil-solutions/inference-optimisation-skill/blob/main/skills/inference-optimisation/references/gotchas.md"
click node_publishing_guidance "https://github.com/sybil-solutions/inference-optimisation-skill/blob/main/skills/inference-optimisation/references/publishing.md"
click node_examples "https://github.com/sybil-solutions/inference-optimisation-skill/tree/main/skills/inference-optimisation/examples"
click node_ceiling_tool "https://github.com/sybil-solutions/inference-optimisation-skill/blob/main/skills/inference-optimisation/scripts/ceiling.py"
click node_benchmark "https://github.com/sybil-solutions/inference-optimisation-skill/blob/main/skills/inference-optimisation/scripts/bench.py"
click node_memory_monitor "https://github.com/sybil-solutions/inference-optimisation-skill/blob/main/skills/inference-optimisation/scripts/mem.sh"
click node_run_queue "https://github.com/sybil-solutions/inference-optimisation-skill/blob/main/skills/inference-optimisation/scripts/queue.sh"
click node_needle_gate "https://github.com/sybil-solutions/inference-optimisation-skill/blob/main/skills/inference-optimisation/scripts/bench.py"
click node_soak "https://github.com/sybil-solutions/inference-optimisation-skill/blob/main/skills/inference-optimisation/SKILL.md"
click node_clean_build "https://github.com/sybil-solutions/inference-optimisation-skill/blob/main/skills/inference-optimisation/references/publishing.md"
click node_acceptance "https://github.com/sybil-solutions/inference-optimisation-skill/blob/main/skills/inference-optimisation/references/publishing.md"
click node_published_results "https://github.com/sybil-solutions/inference-optimisation-skill/blob/main/skills/inference-optimisation/references/publishing.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_skill,node_task_prompt,node_ceiling_guidance,node_measurement_guidance,node_tuning_guidance,node_engine_guidance,node_publishing_guidance toneBlue
class node_ceiling_tool,node_benchmark,node_memory_monitor toneAmber
class node_examples,node_run_queue,node_result_ledger,node_plan,node_local_server toneMint
class node_needle_gate,node_soak,node_clean_build,node_acceptance,node_published_results toneRose
class node_operator toneIndigo
```

## Components

### Procedure and guidance

- [Optimization procedure](https://github.com/sybil-solutions/inference-optimisation-skill/blob/main/skills/inference-optimisation/SKILL.md): `skills/inference-optimisation/SKILL.md`
- [Agent task prompt](https://github.com/sybil-solutions/inference-optimisation-skill/blob/main/PROMPT.md): `PROMPT.md`
- [Ceiling methodology](https://github.com/sybil-solutions/inference-optimisation-skill/blob/main/skills/inference-optimisation/references/ceilings.md): `skills/inference-optimisation/references/ceilings.md`
- [Measurement methodology](https://github.com/sybil-solutions/inference-optimisation-skill/blob/main/skills/inference-optimisation/references/methodology.md): `skills/inference-optimisation/references/methodology.md`
- [Tuning levers](https://github.com/sybil-solutions/inference-optimisation-skill/blob/main/skills/inference-optimisation/references/levers.md): `skills/inference-optimisation/references/levers.md`
- [Engine gotchas](https://github.com/sybil-solutions/inference-optimisation-skill/blob/main/skills/inference-optimisation/references/gotchas.md): `skills/inference-optimisation/references/gotchas.md`
- [Publishing guidance](https://github.com/sybil-solutions/inference-optimisation-skill/blob/main/skills/inference-optimisation/references/publishing.md): `skills/inference-optimisation/references/publishing.md`

### Measurement tools

- [Ceiling calculator](https://github.com/sybil-solutions/inference-optimisation-skill/blob/main/skills/inference-optimisation/scripts/ceiling.py): `skills/inference-optimisation/scripts/ceiling.py`
- [Server benchmark](https://github.com/sybil-solutions/inference-optimisation-skill/blob/main/skills/inference-optimisation/scripts/bench.py): `skills/inference-optimisation/scripts/bench.py`
- [Memory monitor](https://github.com/sybil-solutions/inference-optimisation-skill/blob/main/skills/inference-optimisation/scripts/mem.sh): `skills/inference-optimisation/scripts/mem.sh`

### Experiment workflow

- [Benchmark configurations](https://github.com/sybil-solutions/inference-optimisation-skill/tree/main/skills/inference-optimisation/examples): `skills/inference-optimisation/examples`
- [Serialized run queue](https://github.com/sybil-solutions/inference-optimisation-skill/blob/main/skills/inference-optimisation/scripts/queue.sh): `skills/inference-optimisation/scripts/queue.sh`
- **Result ledger**
- **Tuning plan**

### Validation and release

- [Long-context retrieval gate](https://github.com/sybil-solutions/inference-optimisation-skill/blob/main/skills/inference-optimisation/scripts/bench.py): `skills/inference-optimisation/scripts/bench.py`
- [Full-KV concurrency soak](https://github.com/sybil-solutions/inference-optimisation-skill/blob/main/skills/inference-optimisation/SKILL.md): `skills/inference-optimisation/SKILL.md`
- [Pinned clean build](https://github.com/sybil-solutions/inference-optimisation-skill/blob/main/skills/inference-optimisation/references/publishing.md): `skills/inference-optimisation/references/publishing.md`
- [Acceptance gates](https://github.com/sybil-solutions/inference-optimisation-skill/blob/main/skills/inference-optimisation/references/publishing.md): `skills/inference-optimisation/references/publishing.md`
- [Published results](https://github.com/sybil-solutions/inference-optimisation-skill/blob/main/skills/inference-optimisation/references/publishing.md): `skills/inference-optimisation/references/publishing.md`

### Other components

- **Engineer or agent**
- **OpenAI-compatible server**

## Connections

- Engineer or agent → Optimization procedure: follows procedure (evidence: `README.md`)
- Engineer or agent → Agent task prompt: uses prompt (evidence: `README.md`)
- Optimization procedure → Ceiling methodology: consults (evidence: `README.md`)
- Optimization procedure → Measurement methodology: consults (evidence: `README.md`)
- Optimization procedure → Tuning levers: consults (evidence: `README.md`)
- Optimization procedure → Engine gotchas: consults (evidence: `README.md`)
- Optimization procedure → Publishing guidance: consults (evidence: `README.md`)
- Engineer or agent → Ceiling calculator: computes ceilings (evidence: `README.md`)
- Benchmark configurations → Ceiling calculator: provides inputs (evidence: `README.md`)
- Engineer or agent → Server benchmark: runs benchmark (evidence: `README.md`)
- Benchmark configurations → Server benchmark: configures run (evidence: `README.md`)
- Server benchmark → OpenAI-compatible server: sends requests (evidence: `README.md`)
- Server benchmark → Result ledger: logs results (evidence: `README.md`)
- Engineer or agent → Memory monitor: checks footprint (evidence: `README.md`)
- Engineer or agent → Serialized run queue: queues runs (evidence: `README.md`)
- Serialized run queue → Server benchmark: runs controls (evidence: `README.md`)
- Result ledger → Tuning plan: informs tuning (evidence: `README.md`)
- Tuning plan → Engineer or agent: guides next change (evidence: `README.md`)
- Server benchmark → Long-context retrieval gate: checks retrieval (evidence: `README.md`)
- Long-context retrieval gate → Full-KV concurrency soak: precedes soak (evidence: `README.md`)
- Full-KV concurrency soak → Pinned clean build: precedes qualification (evidence: `README.md`)
- Pinned clean build → Acceptance gates: runs gates (evidence: `README.md`)
- Acceptance gates → Published results: qualifies results (evidence: `README.md`)
