wtf-perf 0.2.1__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- wtf_perf/__init__.py +5 -0
- wtf_perf/__main__.py +6 -0
- wtf_perf/_vendor/__init__.py +0 -0
- wtf_perf/_vendor/ailib/_VENDORED.md +153 -0
- wtf_perf/_vendor/ailib/__init__.py +1 -0
- wtf_perf/_vendor/ailib/analyzer.py +177 -0
- wtf_perf/_vendor/ailib/backend.py +95 -0
- wtf_perf/_vendor/ailib/cache.py +131 -0
- wtf_perf/_vendor/ailib/parsers.py +52 -0
- wtf_perf/_vendor/ailib/transports/__init__.py +16 -0
- wtf_perf/_vendor/ailib/transports/cli.py +342 -0
- wtf_perf/_vendor/ailib/transports/openai_compat.py +400 -0
- wtf_perf/_vendor/ailib/transports/prompt_file.py +41 -0
- wtf_perf/_vendor/ailib/types.py +230 -0
- wtf_perf/_version.py +96 -0
- wtf_perf/aiwire.py +206 -0
- wtf_perf/cli.py +101 -0
- wtf_perf/kits/core.kit.json +13 -0
- wtf_perf/lib/__init__.py +1 -0
- wtf_perf/lib/counters.py +85 -0
- wtf_perf/lib/families.py +114 -0
- wtf_perf/lib/findings.py +160 -0
- wtf_perf/lib/ledger.py +147 -0
- wtf_perf/lib/render.py +168 -0
- wtf_perf/lib/sampler.py +182 -0
- wtf_perf/paths.py +15 -0
- wtf_perf/platforms/__init__.py +41 -0
- wtf_perf/platforms/base.py +98 -0
- wtf_perf/platforms/darwin.py +11 -0
- wtf_perf/platforms/linux.py +12 -0
- wtf_perf/platforms/windows.py +252 -0
- wtf_perf/tools/core/cpu/.wtf-perf.json +21 -0
- wtf_perf/tools/core/cpu/cpu.py +216 -0
- wtf_perf-0.2.1.dist-info/METADATA +164 -0
- wtf_perf-0.2.1.dist-info/RECORD +39 -0
- wtf_perf-0.2.1.dist-info/WHEEL +5 -0
- wtf_perf-0.2.1.dist-info/entry_points.txt +2 -0
- wtf_perf-0.2.1.dist-info/licenses/LICENSE +674 -0
- wtf_perf-0.2.1.dist-info/top_level.txt +1 -0
wtf_perf/__init__.py
ADDED
wtf_perf/__main__.py
ADDED
|
File without changes
|
|
@@ -0,0 +1,153 @@
|
|
|
1
|
+
# The AI library: our fork of record
|
|
2
|
+
|
|
3
|
+
## What this directory is
|
|
4
|
+
|
|
5
|
+
A copy of wtf-windows' `lib/ai`, taken byte-for-byte on 2026-09-03 and **customised here since** -- our own instance of the vendor, in the way a git subtree is. It is not a read-only mirror, and it is no longer required to match its origin byte for byte.
|
|
6
|
+
|
|
7
|
+
That is a deliberate change of policy, made 2026-09-05. The earlier version of this file locked the copy with a hash table and a test that failed on a changed byte, on the assumption that the copy's job was to stay cheaply re-syncable. The maintainer's correction:
|
|
8
|
+
|
|
9
|
+
> Our vendored copy is OPEN to improvements, we don't need it to be byte-identical. In fact the entire point is for our version to BECOME the real library. SO if we can improve the library we absolutely should be doing so.
|
|
10
|
+
|
|
11
|
+
The reasoning behind accepting it, and what replaced the lock, is in `2026-09-05__15-25-29__dev-workflow-process__what-the-ai-library-is.md` (project-private), with a correction in its addendum of the same day. The short version: upstream's `lib/ai` has not changed since we copied it, so there is no divergence to reconcile; the maintainer has said which copy is the one to develop; and the origin **does** have a live caller -- `wtf locked --ai` (`tools/core/locked/locked.py`, a registered tool) imports `analyze` and `check_available` -- which makes wtf-windows a real consumer of the library this tree is becoming, not a reason to freeze the tree. (An earlier version of this paragraph said nothing there called `analyze()`. That came from a search of `src/` that never covered `tools/`; it was wrong, and it was not the reason the policy changed.)
|
|
12
|
+
|
|
13
|
+
## The guarantee this tree owes
|
|
14
|
+
|
|
15
|
+
**Purity, not sameness.** What makes a copy adoptable by another project is that it names nothing of its host -- not that it matches a hash. So, enforced by `tests/test_vendored_ailib.py` over **every** file here, copied or authored:
|
|
16
|
+
|
|
17
|
+
- no import of `dazzle_claude_config`, and no relative import climbing out of `_vendor/ailib`;
|
|
18
|
+
- none of ccs's own tokens anywhere in the text;
|
|
19
|
+
- the standard library only (`pyproject.toml` keeps `dependencies = []`).
|
|
20
|
+
|
|
21
|
+
Break any of those and the tree stops being liftable, which is the only property that matters now.
|
|
22
|
+
|
|
23
|
+
**And honesty.** A file that differs from what we copied must say so in *Changes since the copy* below. The test enforces that too: an edited file with no entry fails. A fork of record is only useful while its record is true, and the failure mode of a fork is a record that quietly rots.
|
|
24
|
+
|
|
25
|
+
## Origin
|
|
26
|
+
|
|
27
|
+
| | |
|
|
28
|
+
|---|---|
|
|
29
|
+
| Repository | `wtf-windows` (local checkout `C:\code\wtf-windows` on plzwork; DazzleML) |
|
|
30
|
+
| Path | `src/wtf_windows/lib/ai/` |
|
|
31
|
+
| Commit | `a795fe51d552a5fade87c39d6f99ffe2c65fcaaa` -- the last commit touching that directory (2026-03-18); the repository's HEAD at copy time was `a2f993b` (v0.1.7-alpha, 2026-06-10) |
|
|
32
|
+
| Copied | 2026-09-03, with the OS (`cp -p`), never retyped |
|
|
33
|
+
| Upstream since | unchanged as of 2026-09-05 (`git log a795fe5..HEAD -- src/wtf_windows/lib/ai/` is empty) |
|
|
34
|
+
|
|
35
|
+
## Copied files, and the fingerprint each arrived with
|
|
36
|
+
|
|
37
|
+
These hashes record **what we received**, so a reader can tell an edited file from an untouched one and see exactly what the delta is against. They are no longer a lock. sha256 over LF-normalised bytes (`\r\n` -> `\n`), because `claude.py` and `codex.py` are CRLF on disk upstream and git may re-line-end any of them.
|
|
38
|
+
|
|
39
|
+
| file | lines at copy | sha256 as received |
|
|
40
|
+
|---|---|---|
|
|
41
|
+
| `__init__.py` | 1 | f9802ac6f4dd911bf77d1a0943356bfb541347bd0212f6259427dfd69758bfa7 |
|
|
42
|
+
| `analyzer.py` | 276 | 0f5eb8aacde228553a2f0f7ef6c45130e9008b79286461efb9d84af9884f5424 |
|
|
43
|
+
|
|
44
|
+
657 lines in six files, as received; two remain. The other four were **removed on 2026-09-05** (U3 of the seam rebuild) once every measured fact they carried had a home and a test in `transports/`. Their fingerprints stay here so the record keeps what was received -- in a separate table, with the date last, so the honesty test does not look for them on disk:
|
|
45
|
+
|
|
46
|
+
| file | lines at copy | sha256 as received | removed |
|
|
47
|
+
|---|---|---|---|
|
|
48
|
+
| `backends/__init__.py` | 1 | d154191a869c6c1930de58dcaa841130dba8b3737687d951887fe4db43c20285 | 2026-09-05 |
|
|
49
|
+
| `backends/claude.py` | 155 | 10ff167263b7cd2e21e241daa5c137c262ceefaaf63133c2fb6eb6d580227e76 | 2026-09-05 (the env scrub, the `~/.local/bin` candidates and the streaming reader live in `transports/cli.py`) |
|
|
50
|
+
| `backends/codex.py` | 171 | e44b935da2e27e7bce62373b07c827536e857c83a738f75836c0810a4bb793cc | 2026-09-05 (the npm/WinGet shim candidates and the `--version` validation live in `transports/cli.py`) |
|
|
51
|
+
| `backends/prompt_only.py` | 53 | 613b11217523490ba1f3ffd1acfc7e1716e64a16ee615ed6a4b885d43b8b2479 | 2026-09-05 (`transports/prompt_file.py`) |
|
|
52
|
+
|
|
53
|
+
## Changes since the copy
|
|
54
|
+
|
|
55
|
+
Every file below differs from the fingerprint above, or was written here. One entry each, dated, with why.
|
|
56
|
+
|
|
57
|
+
- **`backends/lmstudio.py` -- written here 2026-09-04, absorbed 2026-09-05.** The first HTTP backend in the house, and the measurements it was built on (LM Studio answers `json_object` with HTTP 400 but honours a strict `json_schema`; `reasoning_effort: "none"` is the only thinking-suppression that reaches the model; an HTTP 200 can carry empty content; `/v1/models` lists what is downloaded while `/api/v0/models`, off the server ROOT, says what is loaded; a client timeout does not cancel server work; throughput is dominated by the context window). All of it now lives in `transports/openai_compat.py`, generalised so that the same code serves LM Studio, Ollama, OpenAI and OpenRouter -- the module-level `configure`/`set_schema` state it kept is gone with it, replaced by the spec. Removed in U3.
|
|
58
|
+
|
|
59
|
+
- **The object model -- written here, 2026-09-05** (`types.py`, `backend.py`, `cache.py`, `parsers.py`, `transports/__init__.py`, `transports/cli.py`, `transports/openai_compat.py` -- renamed from `transports/openai.py` on 2026-09-06, the protocol's name rather than the company's, so that a preset called `openai` is read as one rider of the transport and never as the transport itself; the registry key changed with it -- `transports/prompt_file.py`). A backend is a frozen `Spec` (transport, endpoint, model, the *name* of a credential variable, an argv template, an answer locator) built into a `Backend` with `probe()` and `invoke(Request)`; three transports, one per way of reaching a model, so local versus remote is a preset's endpoint and key rather than code; a `Response` whose status is a word; `cache.run()` keyed on the backend's own identity so a caller never learns which facts matter for which transport; two generic readers. Replaces the name-keyed `backends/` modules and their module-level state, which the deletions in U3 remove once every measured fact they carried (LM Studio's load-state probe and empty-content guard, claude's environment scrub, codex's shim validation) has a home and a test here. Design: `2026-09-05__16-52-32__dev-workflow-process__the-ai-object-model-one-door-two-consumers.md` (project-private); the POC that earned it is `tests/one-offs/thinking/ai-object-model/`.
|
|
60
|
+
- **`types.py` and `transports/openai_compat.py` -- edited 2026-09-09: file-based credentials.** `Spec` gains `credential_file` (a key file named on purpose, read BEFORE the environment) and `credential_fallbacks` (files read only when the environment has nothing -- a tool's default key location); both hold paths, never a value, and `identity()` names each by its basename as `keyfile:<name>` so a moved home does not flush a cache and a record pasted into an issue carries no account name. The transport reads the file at request time (`_read_key_file`: `NAME=value` lines looked up by `credential_env`, `export ` and quotes and comments and CRLF and a BOM tolerated, a single bare line is the value, 64 KB cap), resolves the three sources in that fixed order (`_credential` -> value and its source), sends the value in one header, refuses with a sentence naming the variable AND every file with why each gave nothing (`_missing_key`), and says `key from <source>` in the probe's reason -- with a POSIX warning when the file is readable by group or others. Why: a hosted preset's key had one home, the environment, and a person who keeps keys in files had to export them by hand before every run. Design: `2026-09-06__22-01-24__dev-workflow-process__the-deep-merge-meaning-over-git-s-clean-regions.md`, the four notes on question 7 (project-private).
|
|
61
|
+
- **`types.py` and `transports/cli.py` -- edited 2026-09-09: a populated working directory and the `tools` grant.** `Request` gains `workdir` (a directory the caller prepared for the backend to work in; excluded from the fingerprint like `stream_to`), `Spec` gains `tools` (what the new `{tools}` placeholder becomes) and the capability name `TOOLS`. The cli transport runs the child in the workdir when one is named -- and leaves it as the child left it, for the caller to read back -- while still making and removing its own scratch for the call's schema and prompt files; `{cwd}` names the workdir then; `{tools}` is substituted from `spec.tools` only when a workdir is named, so a preset's grant never reaches a call that gave the child nothing to work in and a call without a workdir is argv-identical to before; `capabilities()` says `tools` only with both the placeholder and a grant. Why: the deep merge (#64) runs a CLI inside a sandbox copy and needs the CLI's own sandbox as its first layer (measured 2026-09-09: claude's `--allowedTools Read,Grep,Edit,Write` and codex's `-s workspace-write` write only inside the cwd; the read-only forms refuse). Design: `2026-09-06__22-01-24__dev-workflow-process__the-deep-merge-meaning-over-git-s-clean-regions.md` (project-private).
|
|
62
|
+
- **`types.py` -- edited 2026-09-09 (later the same day): the identity without empty fields.** `Spec.identity()` used to join every field with `|`, so a CLI preset read `cli|||claude --output-format ...` and a server preset `openai_compat|http://...|||` -- a string people meet in records and reports, saying nothing about which fields were empty. It now names only the parts that exist, labelled (`cli command=...`, `openai_compat endpoint=... model=... extra=...`), keeping the `key:` and `keyfile:` spellings the earlier tests and records pin. The identity keys the answer cache, so this is one invalidation, folded with the `{tools}` placeholder change of the same day. Issue #63 in the consuming project.
|
|
63
|
+
- **`types.py` and `transports/cli.py` -- edited 2026-09-18: run while alive.** A call used to end on one number, `Request.timeout = 120`, handed to `subprocess.run` or polled by the streaming reader. Measured before the change: the deep step on Claude Opus over a real file was cut at 120 s while Claude Code's own transcript showed it reading and thinking the whole time (five tool calls, 91 s of thought on a 48k-character prompt), and a probe of `--output-format stream-json --verbose --include-partial-messages` showed thinking arriving as an event every second or so, the longest silence 1.6 s. So `Request` gains `idle` (default 180: the silence after which a child that has shown no sign of life is killed) and `timeout` becomes a ceiling that is off by default (0); both stay outside the fingerprint. Every call now goes through the streaming reader, whether or not the caller echoes the lines, because the lines are the sign of life; the reader is started before the prompt is written so a large prompt cannot deadlock a talkative child; the two ways a call ends carry different sentences (`gave no sign of life for Ns -- stopped` / `ran past the Ns ceiling you set -- stopped`). `Spec` gains `max_turns` (the `{turns}` placeholder, a CLI's own budget of agentic turns, the cost fence for a call that may run as long as it is alive; part of the identity because it bounds the answer) and the `stream-json:<key>` answer locator (one JSON event per line; the answer is a key of the last `result` event; an `is_error` result is a failure carrying its text). `transports/openai_compat.py` does not stream yet: it takes `timeout or idle` as its ceiling (a zero timeout on `urlopen` fails at once), and its timeout sentence names that number; streaming it is the design's second unit. Design: `2026-09-18__03-06-39__dev-workflow-process__run-while-alive-the-ai-step-s-timeout-becomes-a-hang-detector.md` (project-private).
|
|
64
|
+
- **`analyzer.py` -- edited 2026-09-05, twice.** First, the defect: `analyze(refresh=True)` raised `UnboundLocalError` (the cache key was bound only under `if not refresh`, then read at the write) -- verbatim upstream, where `wtf locked --ai --ai-refresh` crashed; fixed by computing the key once. Then, the same day, `analyze()` and `check_available()` became **thin compatibility wrappers** over the object model: the signature and the four-key result dict are kept for the one live caller (`wtf locked`), the body is `build` -> `probe` -> `cache.run` -> `parsers.sections` with no logic of its own, and a three-name table (`_COMPAT_PRESETS`) maps the origin's `claude` / `codex` / `prompt-only` to specs. Both carry `COMPAT(remove-after: wtf locked migrates to build/run)`; `tests/test_compat_markers.py` holds the inventory. Pinned by `tests/test_analyze_shim.py` with the caller's exact call shape.
|
|
65
|
+
|
|
66
|
+
## Queued improvements -- delivered 2026-09-05
|
|
67
|
+
|
|
68
|
+
Written on the morning of 2026-09-05 as a queue for "after the release"; delivered the same afternoon, because the maintainer's review of the seam found the queue was the design. All three landed in the object model above rather than as patches to the old shape:
|
|
69
|
+
|
|
70
|
+
1. **Configuration per call** -- became *configuration in the object*: a `Spec` is built once, the `Request` carries only what varies per call, and no transport keeps module state. The POC that earned it (`tests/one-offs/thinking/backend-config-per-call/`, then `tests/one-offs/thinking/ai-object-model/`) is retained.
|
|
71
|
+
2. **`--model` for codex** -- the preset carries `-m {model}` and the backend's capabilities say so; the facade table that admitted the gap is gone.
|
|
72
|
+
3. **The two generic things the facade held** -- the scratch working directory is the `cli` transport's (handed to the child, never `os.chdir`), and the fenced-JSON reader is `parsers.json_block`.
|
|
73
|
+
|
|
74
|
+
## Destiny
|
|
75
|
+
|
|
76
|
+
The standalone `dazzle-ailib` -- a perpendicular member of the family depending only on `dazzle-lib` -- with wtf-windows, wtf-restarted and ccs as its consumers (three, which clears the stack map's rule of two).
|
|
77
|
+
|
|
78
|
+
Note what already exists: **wtf-restarted's copy differs from wtf-windows' in five of the six files** and carries a `prompts/` directory. So there are already three copies of this code in the house and they have already diverged. Reconciling them is that library's first job. What changed on 2026-09-05 is only which copy is the one to reconcile *towards*: this one, because it is the one under active development and the only one with a test suite over it.
|
|
79
|
+
|
|
80
|
+
Design of record for the original vendoring: `2026-09-01__14-25-05__dev-workflow-process__ccs-merge-ai-the-shared-ai-library-and-the-remap-step.md`, refactor-session addendum. For the policy change: the 2026-09-05 analysis named above.
|
|
81
|
+
|
|
82
|
+
## Extraction checklist
|
|
83
|
+
|
|
84
|
+
When the standalone library exists:
|
|
85
|
+
|
|
86
|
+
1. `pip`-install it and add it to `dependencies` -- gated on the dependency policy (issue #34), and not before a zeromeld adoption has shipped once more with no dependency at all.
|
|
87
|
+
2. Point `dazzle_claude_config/ailib.py`'s imports at the library instead of `._vendor.ailib`; the registry rebinding goes away once the library names its own backends.
|
|
88
|
+
3. Delete this directory. Nothing else in ccs imports it -- the purity test proves nothing here reaches into ccs, and a grep for `_vendor` outside `ailib.py` and that test proves the reverse.
|
|
89
|
+
4. Carry the *Changes since the copy* list into the library's own history, or it is lost.
|
|
90
|
+
|
|
91
|
+
## Comparing against the origin
|
|
92
|
+
|
|
93
|
+
```
|
|
94
|
+
git -C C:\code\wtf-windows diff a795fe5 -- src/wtf_windows/lib/ai
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
or file by file, line-endings normalised:
|
|
98
|
+
|
|
99
|
+
```
|
|
100
|
+
diff <(sed 's/\r$//' C:/code/wtf-windows/src/wtf_windows/lib/ai/analyzer.py) <(sed 's/\r$//' dazzle_claude_config/_vendor/ailib/analyzer.py)
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
## Facade
|
|
104
|
+
|
|
105
|
+
`dazzle_claude_config/ailib.py` -- the only module in ccs that imports anything under `_vendor/` (a test in `tests/test_vendored_ailib.py` proves the reverse direction too). Since 2026-09-05 it is the **presets**, not a compatibility layer:
|
|
106
|
+
|
|
107
|
+
- `PRESETS` -- the named backends a person types after `--ai`, as data over the library's transports: `claude`, `claude-strict`, `codex`, `codex-strict` (transport `cli`, with the argv the live runs proved and, for the strict pair, an answer locator); `lmstudio`, `ollama`, `openai`, `openrouter` (transport `openai`, differing only in endpoint, extras and the name of a credential variable). Local versus remote is an endpoint and a key, never code;
|
|
108
|
+
- `names()`, `spec_for(name, *, endpoint, model, api_key_env)`, `build_backend(opts)` -- the person's overrides applied to a preset, and the object the caller talks to;
|
|
109
|
+
- re-exports of the library's `build`, `run`, `Request` and `parsers`, so nothing else in ccs imports `_vendor`.
|
|
110
|
+
|
|
111
|
+
Everything the old facade did to compensate for a foreign copy -- the registry rebinding, the `os.chdir` scratch directory, the `ANTHROPIC_MODEL` route, the per-backend setters, its own JSON reader -- is gone: the transports own those properties now, with tests.
|
|
112
|
+
|
|
113
|
+
## wtf-perf's copy -- the fork of record from 2026-11-18
|
|
114
|
+
|
|
115
|
+
**This copy is now the one the others reconcile towards.** The maintainer, 2026-11-18, asked which copy becomes the first release: "wtf-perf's copy (Recommended)". The library's first-release work (ccs's tests ported, the cache and purity fixes, new fields) happens here; ccs and git-repokit keep running their copies unchanged and re-vendor from this one later. Plan: `2026-11-18__21-10-06__DISCUSS_Rnd3_FINAL_ASSESSMENT_(ai-library-design).md` (wtf-perf's private notes).
|
|
116
|
+
|
|
117
|
+
**Licence.** Every line of this tree was written by the maintainer, its sole author (the commits in wtf-windows `lib/ai` and in ccs are all his). Here it is offered under wtf-perf's licence (GPL-3.0-or-later); its destination is the MIT-licensed DazzleLib collection (STACK-MAP D11), and contributions to `_vendor/ailib/` are accepted under MIT so that it can move there.
|
|
118
|
+
|
|
119
|
+
**Source.** Copied with the OS, never retyped, on 2026-11-18 from dazzle-claude-config-tool's `ccs-ai-pass-1` worktree (commit 63ad163, 2026-10-02) -- the newest copy, the same one git-repokit took on 2026-10-24. It differs from ccs `main` by one hunk in `transports/openai_compat.py` (the warning when a hosted endpoint answers with a model nobody chose).
|
|
120
|
+
|
|
121
|
+
**Known host leak (fixed 2026-11-18, see Changes below):** the hunk's sentence ended with a ccs setting name.
|
|
122
|
+
|
|
123
|
+
### Received fingerprints (sha256 over LF-normalised bytes)
|
|
124
|
+
|
|
125
|
+
| file | lines | sha256 as received |
|
|
126
|
+
|---|---|---|
|
|
127
|
+
| `__init__.py` | 1 | f9802ac6f4dd911bf77d1a0943356bfb541347bd0212f6259427dfd69758bfa7 |
|
|
128
|
+
| `analyzer.py` | 177 | 6033d1ffb253a0340f5199d9bc956c9d3d045097ba5142166ab3463b68b41c42 |
|
|
129
|
+
| `backend.py` | 95 | 9cfbdf6a243d61cabe36caf0f3bb60197b9bdb0b72870f5b6cdfec68804a77ee |
|
|
130
|
+
| `cache.py` | 97 | 966079ce01ff9e0f342914b2a9da9537fd82dc851c854a2c1fb4d2b07886c9cd |
|
|
131
|
+
| `parsers.py` | 52 | 11ff29d8d76d0cee2e38b24c2522f9d5baa31146b70e129442093ad3d920fb00 |
|
|
132
|
+
| `transports/__init__.py` | 16 | 2fbbe45539a64176de0c11006d4f6521346f5cd3ba598962496da3da913bdc98 |
|
|
133
|
+
| `transports/cli.py` | 312 | 3946c34fb4b272ef3a317df0af09b40678cc1fe5b4a687c3e59f34cdcb7d735a |
|
|
134
|
+
| `transports/openai_compat.py` | 383 | 4e5624e0803d56420f500767663c4473b67553355d011744ac85d3768541437f |
|
|
135
|
+
| `transports/prompt_file.py` | 41 | 79f590c238d66f07f91ecd7648b6744a5ac2f74bdb1687087a56524ec645df5b |
|
|
136
|
+
| `types.py` | 224 | d7db3b2cedd77b4c505051c55571047f4d489a5fa88b305f97b8ae04d63ccea0 |
|
|
137
|
+
|
|
138
|
+
### Changes in wtf-perf's copy
|
|
139
|
+
|
|
140
|
+
- **`cache.py` -- 2026-11-18: the sweep, a caller key, atomic writes, a format version.**
|
|
141
|
+
- *The sweep deleted host files.* `_sweep` read a missing `cached_at` as 0 and unlinked any dict-shaped `*.json` in the cache directory -- a host's `config.json` placed there was deleted on the first answered call (found by wtf-perf's AI-library consultation, run in a probe). It now removes only JSON objects carrying a numeric `cached_at` older than the TTL; ccs's "any file name" behaviour and its test are unchanged.
|
|
142
|
+
- *A caller key.* `run(..., key=)` and `cache_key(..., key=)`: when given, the entry is keyed on that key plus the backend's identity and the tool, not on the full prompt. The prompt-derived key made "the same question with fresh evidence" a miss every time; `wtf locked`'s migration off `analyze()` needs its stable-field key back.
|
|
143
|
+
- *Atomic writes.* An entry is written to a temp file in the same directory and moved into place with `os.replace` (the idiom dazzle-filekit's `atomic_write_text` uses), so a reader never sees half an entry.
|
|
144
|
+
- *A format version.* Entries carry `"format": 1`; an entry without one reads as format 1, so existing caches stay valid.
|
|
145
|
+
- Tests: `tests/ailib/test_wtf_perf_changes.py` (5); the ported ccs cache tests still pass.
|
|
146
|
+
- **`transports/openai_compat.py` -- 2026-11-18: the host leak removed; the cancellation claim corrected.**
|
|
147
|
+
- *Host leak.* The "model nobody chose" warning ended "set ai_merge_model to choose", a ccs setting name. It now ends with the spec's own `hint` (the host's words), or "name a model to choose". `ai_merge_` joined the purity test's host tokens, which pass.
|
|
148
|
+
- *Cancellation.* The module docstring said a client timeout does not cancel server-side work. Measured on LM Studio 2026-11-18 (wtf-perf's `tests/one-offs/probe_lmstudio_timeout_cancel.py`): a 2 s client timeout on a stream:false request was followed the same second by "Client disconnected. Stopping generation" and "cancel task" in the server log. The docstring now says so and that other servers are unmeasured. Behaviour unchanged (still no retry).
|
|
149
|
+
- **`transports/cli.py` -- 2026-11-18: Windows executable lookup.** `find_exe` asked `shutil.which` first, which returned an extension-less POSIX shim named `claude` on PATH that Windows cannot run (WinError 193). On Windows a bare name is now matched against each PATH directory with the PATHEXT extensions first (what CreateProcess runs), then `shutil.which`, then the candidates. Standard library only (the same rule as dazzlecmd-lib's `which_with_pathext`, which the library may not import). Test: `tests/ailib/test_wtf_perf_changes.py::test_windows_lookup_prefers_a_runnable_extension_over_a_posix_shim`; also two field-enumeration tests there pin `Request.fingerprint` and the cache entry against new fields.
|
|
150
|
+
- **`transports/cli.py` -- 2026-11-18: kill the child on interrupt.** `_stream`'s wait loop had no `finally`, so a Ctrl-C (KeyboardInterrupt) while waiting left the CLI child running. The loop now kills the child on any way out that is not a normal exit. Test: `test_an_interrupt_in_the_reader_kills_the_child` (red without the change).
|
|
151
|
+
- **`types.py` -- 2026-11-18: `Response.reasoning` and `Response.finish_reason`.** Two optional trailing fields, `""` when unknown, deliberately not cached (a hit returns `""`). Measured shape on LM Studio (wtf-perf's `tests/one-offs/probe_lmstudio_stream.py`): a non-streamed reply's message carries `reasoning_content` beside `content`, and the choice carries `finish_reason`; streamed deltas carry them as separate fields too. The field-enumeration test declares both as not cached.
|
|
152
|
+
- **`transports/openai_compat.py` -- 2026-11-18: fills those fields; `localhost` rewritten at connect time.** The answer path reads `message.reasoning_content` (or `reasoning`) and `choices[0].finish_reason` into the new fields, also on the empty-content failure. A new `connectable(url)` turns `localhost` into `127.0.0.1` at connect time only (both the GET helper and the chat request): measured ~2 s per request against an IPv4-only server via `localhost`, 0.002-0.02 s via `127.0.0.1`. The spec's endpoint and identity are unchanged. Tests: two in `tests/ailib/test_transport_openai_compat.py` (the fake server gained optional `reasoning_content` and `finish_reason`), one in `test_wtf_perf_changes.py`.
|
|
153
|
+
- **Deferred, with its trigger:** opt-in leading-`<think>` stripping (from the C# transport) -- no caller yet; reopens when a host uses a server that inlines `<think>` blocks in `content`.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
"""AI analysis pipeline for wtf-windows diagnostic tools."""
|
|
@@ -0,0 +1,177 @@
|
|
|
1
|
+
"""Shared AI analysis pipeline for wtf-windows diagnostic tools.
|
|
2
|
+
|
|
3
|
+
Orchestrates prompt building, backend invocation, and response parsing.
|
|
4
|
+
Each tool supplies its own domain-specific functions:
|
|
5
|
+
|
|
6
|
+
from wtf_windows.lib.ai.analyzer import analyze
|
|
7
|
+
|
|
8
|
+
result = analyze(
|
|
9
|
+
results=investigation_data,
|
|
10
|
+
fingerprint_fn=my_stable_fields, # tool-specific cache fingerprint
|
|
11
|
+
prompt_path=Path("prompts/diagnose.md"),
|
|
12
|
+
cache_dir=Path.home() / ".wtf-locked" / "cache",
|
|
13
|
+
tool_name="locked",
|
|
14
|
+
)
|
|
15
|
+
|
|
16
|
+
The analyzer handles caching, backend dispatch, and response parsing.
|
|
17
|
+
Tools handle what makes their events semantically unique.
|
|
18
|
+
"""
|
|
19
|
+
|
|
20
|
+
import hashlib
|
|
21
|
+
import json
|
|
22
|
+
import re
|
|
23
|
+
import sys
|
|
24
|
+
import time
|
|
25
|
+
from pathlib import Path
|
|
26
|
+
from typing import Any, Callable, Dict, List, Optional, Tuple
|
|
27
|
+
|
|
28
|
+
from .backend import build as _build
|
|
29
|
+
from .cache import run as _run
|
|
30
|
+
from .parsers import sections as _sections
|
|
31
|
+
from .types import Request as _Request, Spec as _Spec
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
# The three names the ORIGINAL front door knew, as specs over the object
|
|
35
|
+
# model. This is the shim's table, not a registry: a consumer that wants
|
|
36
|
+
# its own names keeps them on its own side and builds specs itself. The argv
|
|
37
|
+
# is what the original backends ran; the prompt-only directory is the
|
|
38
|
+
# original default.
|
|
39
|
+
#
|
|
40
|
+
# COMPAT(remove-after: wtf locked migrates to build/run)
|
|
41
|
+
_COMPAT_PRESETS = {
|
|
42
|
+
"claude": _Spec("cli", name="claude",
|
|
43
|
+
command=("claude", "--output-format", "text", "-p", "-"),
|
|
44
|
+
env_unset=("CLAUDECODE", "CLAUDE_CODE_ENTRYPOINT"),
|
|
45
|
+
candidates=("~/.local/bin/claude.exe", "~/.local/bin/claude"), on_prem=False),
|
|
46
|
+
"codex": _Spec("cli", name="codex",
|
|
47
|
+
command=("codex", "exec", "--skip-git-repo-check", "-"),
|
|
48
|
+
candidates=("%APPDATA%/npm/codex.cmd",
|
|
49
|
+
"%LOCALAPPDATA%/Microsoft/WinGet/Links/codex.cmd"), on_prem=False),
|
|
50
|
+
"prompt-only": _Spec("prompt-file", name="prompt-only",
|
|
51
|
+
endpoint=str(Path.home() / ".wtf-windows" / "ai")),
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
def check_available(backend_name="claude"):
|
|
55
|
+
"""Whether one of the original three backends is ready, by name.
|
|
56
|
+
|
|
57
|
+
A thin wrapper: the answer is `build(spec).probe().ok` for the spec the
|
|
58
|
+
name maps to. A consumer on the object model asks its backend directly.
|
|
59
|
+
|
|
60
|
+
COMPAT(remove-after: wtf locked migrates to build/run)
|
|
61
|
+
"""
|
|
62
|
+
spec = _COMPAT_PRESETS.get(backend_name)
|
|
63
|
+
if spec is None:
|
|
64
|
+
return False
|
|
65
|
+
return _build(spec).probe().ok
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
def build_prompt(results, prompt_path, clean_fn=None):
|
|
69
|
+
"""Build the AI analysis prompt from investigation results.
|
|
70
|
+
|
|
71
|
+
Args:
|
|
72
|
+
results: dict from the tool's investigation
|
|
73
|
+
prompt_path: Path to the tool's prompt template (.md file)
|
|
74
|
+
clean_fn: Optional function to clean results before embedding in prompt
|
|
75
|
+
(e.g., removing large raw_output fields to save tokens)
|
|
76
|
+
|
|
77
|
+
Returns:
|
|
78
|
+
str: The complete prompt text
|
|
79
|
+
"""
|
|
80
|
+
template = prompt_path.read_text(encoding="utf-8")
|
|
81
|
+
|
|
82
|
+
evidence = clean_fn(results) if clean_fn else results
|
|
83
|
+
evidence_json = json.dumps(evidence, indent=2, default=str)
|
|
84
|
+
|
|
85
|
+
# Replace template placeholders
|
|
86
|
+
prompt = template.replace("{evidence_json}", evidence_json)
|
|
87
|
+
|
|
88
|
+
# Optional dump section (for tools that include crash dump analysis)
|
|
89
|
+
dump_section = ""
|
|
90
|
+
raw_output = (results.get("dump_analysis") or {}).get("raw_output")
|
|
91
|
+
if raw_output:
|
|
92
|
+
lines = raw_output.splitlines()
|
|
93
|
+
if len(lines) > 200:
|
|
94
|
+
raw_output = "\n".join(lines[-200:])
|
|
95
|
+
raw_output = f"[...truncated to last 200 lines...]\n{raw_output}"
|
|
96
|
+
dump_section = (
|
|
97
|
+
"\n## Crash Dump Analysis (kd.exe !analyze -v output)\n\n"
|
|
98
|
+
f"```\n{raw_output}\n```\n"
|
|
99
|
+
)
|
|
100
|
+
prompt = prompt.replace("{dump_section}", dump_section)
|
|
101
|
+
|
|
102
|
+
return prompt
|
|
103
|
+
|
|
104
|
+
|
|
105
|
+
def analyze(
|
|
106
|
+
results,
|
|
107
|
+
fingerprint_fn,
|
|
108
|
+
prompt_path,
|
|
109
|
+
cache_dir,
|
|
110
|
+
tool_name,
|
|
111
|
+
backend_name="claude",
|
|
112
|
+
clean_fn=None,
|
|
113
|
+
response_sections=None,
|
|
114
|
+
verbose=False,
|
|
115
|
+
timeout=120,
|
|
116
|
+
refresh=False,
|
|
117
|
+
):
|
|
118
|
+
"""Run AI analysis on investigation results.
|
|
119
|
+
|
|
120
|
+
Args:
|
|
121
|
+
results: dict from the tool's investigation
|
|
122
|
+
fingerprint_fn: Callable[[dict], dict] -- extracts stable fields for
|
|
123
|
+
cache key. Each tool defines what makes its events unique.
|
|
124
|
+
prompt_path: Path to the tool's prompt template
|
|
125
|
+
cache_dir: Path to the tool's cache directory
|
|
126
|
+
tool_name: Tool identifier (included in cache key)
|
|
127
|
+
backend_name: which AI backend to use (claude, codex, prompt-only)
|
|
128
|
+
clean_fn: Optional callable to clean results before prompt building
|
|
129
|
+
response_sections: Optional list of (key, regex_label) for parsing.
|
|
130
|
+
Defaults to What Happened / Why / What To Do / Confidence.
|
|
131
|
+
verbose: stream output in real-time
|
|
132
|
+
timeout: seconds before timing out
|
|
133
|
+
refresh: bypass cache (re-run analysis)
|
|
134
|
+
|
|
135
|
+
Returns:
|
|
136
|
+
dict with keys:
|
|
137
|
+
success: bool
|
|
138
|
+
raw_response: str
|
|
139
|
+
sections: dict (parsed sections)
|
|
140
|
+
error: str or None
|
|
141
|
+
cached: bool (if from cache)
|
|
142
|
+
cached_at: float (if from cache)
|
|
143
|
+
|
|
144
|
+
This is the ORIGINAL front door, kept with its signature and its result
|
|
145
|
+
shape for the one live caller that still uses it (wtf-windows'
|
|
146
|
+
`wtf locked --ai`, tools/core/locked/locked.py). It is a thin wrapper:
|
|
147
|
+
the prompt comes from `build_prompt`, the backend from the three-name
|
|
148
|
+
table above, the answer from `cache.run` over `backend.build`, the
|
|
149
|
+
sections from `parsers.sections`. No logic of its own. The migration is
|
|
150
|
+
one call: `run(build(spec), Request(prompt), cache_dir=..., ...)`.
|
|
151
|
+
|
|
152
|
+
COMPAT(remove-after: wtf locked migrates to build/run)
|
|
153
|
+
"""
|
|
154
|
+
spec = _COMPAT_PRESETS.get(backend_name)
|
|
155
|
+
if spec is None:
|
|
156
|
+
return {"success": False, "raw_response": "", "sections": {},
|
|
157
|
+
"error": f"Unknown AI backend: {backend_name!r}. Available: {', '.join(_COMPAT_PRESETS)}"}
|
|
158
|
+
backend = _build(spec)
|
|
159
|
+
ready = backend.probe()
|
|
160
|
+
if not ready.ok:
|
|
161
|
+
return {"success": False, "raw_response": "", "sections": {},
|
|
162
|
+
"error": f"AI backend '{backend_name}' is not available ({ready.reason})"}
|
|
163
|
+
prompt = build_prompt(results, prompt_path, clean_fn)
|
|
164
|
+
req = _Request(prompt=prompt, timeout=timeout, stream_to=sys.stdout if verbose else None)
|
|
165
|
+
resp = _run(backend, req, cache_dir=Path(cache_dir), fingerprint_extra=fingerprint_fn(results),
|
|
166
|
+
refresh=refresh, tool=tool_name)
|
|
167
|
+
if resp.status == "deferred":
|
|
168
|
+
return {"success": False, "raw_response": "", "sections": {},
|
|
169
|
+
"error": f"Prompt saved to: {resp.artifact}"}
|
|
170
|
+
if not resp.ok:
|
|
171
|
+
return {"success": False, "raw_response": resp.error, "sections": {}, "error": resp.error}
|
|
172
|
+
result = {"success": True, "raw_response": resp.text,
|
|
173
|
+
"sections": _sections(resp.text, response_sections), "error": None}
|
|
174
|
+
if resp.cached:
|
|
175
|
+
result["cached"] = True
|
|
176
|
+
result["cached_at"] = resp.cached_at
|
|
177
|
+
return result
|
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
"""The AI object: a `Spec` bound to a `Transport`.
|
|
2
|
+
|
|
3
|
+
A backend holds its spec and delegates to a transport. It keeps no module
|
|
4
|
+
state, so two backends built from two specs can live in one process -- for
|
|
5
|
+
a caller that asks several models in one run, or one that lives longer than
|
|
6
|
+
a single call -- and neither can leak into the other.
|
|
7
|
+
|
|
8
|
+
Transports are registered by name. The three shipped here are lazily
|
|
9
|
+
imported the first time a backend is built; a consumer (or a test) may
|
|
10
|
+
register its own with `register_transport`.
|
|
11
|
+
"""
|
|
12
|
+
from __future__ import annotations
|
|
13
|
+
|
|
14
|
+
from typing import Protocol, runtime_checkable
|
|
15
|
+
|
|
16
|
+
from .types import Readiness, Request, Response, Spec
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
@runtime_checkable
|
|
20
|
+
class Transport(Protocol):
|
|
21
|
+
"""One per WAY OF REACHING a model. Stateless: everything comes from the
|
|
22
|
+
spec it is handed, so the same transport object serves every backend
|
|
23
|
+
built over it."""
|
|
24
|
+
|
|
25
|
+
def probe(self, spec: Spec) -> Readiness: ...
|
|
26
|
+
def invoke(self, spec: Spec, req: Request) -> Response: ...
|
|
27
|
+
def capabilities(self, spec: Spec) -> frozenset[str]: ...
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
_TRANSPORTS: dict[str, Transport] = {}
|
|
31
|
+
_BUILTIN = ("cli", "openai_compat", "prompt-file")
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
def register_transport(name: str, transport: Transport | None) -> None:
|
|
35
|
+
"""Add a transport under `name`, or remove it with None."""
|
|
36
|
+
if transport is None:
|
|
37
|
+
_TRANSPORTS.pop(name, None)
|
|
38
|
+
else:
|
|
39
|
+
_TRANSPORTS[name] = transport
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
def _ensure_builtins() -> None:
|
|
43
|
+
if all(n in _TRANSPORTS for n in _BUILTIN):
|
|
44
|
+
return
|
|
45
|
+
from .transports import cli, openai_compat, prompt_file
|
|
46
|
+
_TRANSPORTS.setdefault("cli", cli.SubprocessCli())
|
|
47
|
+
# "openai_compat": the OpenAI-compatible wire format every local and
|
|
48
|
+
# hosted server speaks (LM Studio, Ollama, OpenRouter, OpenAI itself).
|
|
49
|
+
# Named for the protocol, not the company, so a preset called "openai"
|
|
50
|
+
# (the hosted API) is one of several riding it and never read as the
|
|
51
|
+
# transport itself.
|
|
52
|
+
_TRANSPORTS.setdefault("openai_compat", openai_compat.OpenAICompatible())
|
|
53
|
+
_TRANSPORTS.setdefault("prompt-file", prompt_file.PromptFile())
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
def transport_names() -> list[str]:
|
|
57
|
+
_ensure_builtins()
|
|
58
|
+
return sorted(_TRANSPORTS)
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
def transport_for(name: str) -> Transport:
|
|
62
|
+
_ensure_builtins()
|
|
63
|
+
try:
|
|
64
|
+
return _TRANSPORTS[name]
|
|
65
|
+
except KeyError:
|
|
66
|
+
raise ValueError(f"unknown transport {name!r} -- one of: {', '.join(sorted(_TRANSPORTS))}") from None
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
class Backend:
|
|
70
|
+
"""The object a caller talks to. Build one with `build(spec)`."""
|
|
71
|
+
|
|
72
|
+
def __init__(self, spec: Spec):
|
|
73
|
+
self.spec = spec
|
|
74
|
+
self._transport = transport_for(spec.transport)
|
|
75
|
+
|
|
76
|
+
@property
|
|
77
|
+
def identity(self) -> str:
|
|
78
|
+
return self.spec.identity()
|
|
79
|
+
|
|
80
|
+
@property
|
|
81
|
+
def capabilities(self) -> frozenset[str]:
|
|
82
|
+
return frozenset(self._transport.capabilities(self.spec))
|
|
83
|
+
|
|
84
|
+
def probe(self) -> Readiness:
|
|
85
|
+
return self._transport.probe(self.spec)
|
|
86
|
+
|
|
87
|
+
def invoke(self, req: Request) -> Response:
|
|
88
|
+
return self._transport.invoke(self.spec, req)
|
|
89
|
+
|
|
90
|
+
def __repr__(self) -> str:
|
|
91
|
+
return f"Backend({self.spec.name or self.spec.transport}: {self.identity})"
|
|
92
|
+
|
|
93
|
+
|
|
94
|
+
def build(spec: Spec) -> Backend:
|
|
95
|
+
return Backend(spec)
|
|
@@ -0,0 +1,131 @@
|
|
|
1
|
+
"""`run()` -- ask a backend through a cache.
|
|
2
|
+
|
|
3
|
+
The key is the backend's own identity plus the request's fingerprint plus
|
|
4
|
+
whatever facts the caller adds (a merge tool adds the three sides and its
|
|
5
|
+
rules; a diagnostic tool adds the event's stable fields), so the caller
|
|
6
|
+
never learns which backend facts matter for which transport. A hit
|
|
7
|
+
reproduces the response the backend gave, marked cached. Nothing is written
|
|
8
|
+
for a deferred or failed answer. A refresh skips the read and still writes.
|
|
9
|
+
|
|
10
|
+
A write also sweeps entries older than the TTL from the cache directory
|
|
11
|
+
under ANY file name: an entry that is never looked up again would otherwise
|
|
12
|
+
never expire. Only files that ARE cache entries -- a JSON object carrying a
|
|
13
|
+
numeric `cached_at` -- are swept; a host file that shares the directory (a
|
|
14
|
+
config.json, say) is left alone. (Until 2026-11-18 the sweep read a missing
|
|
15
|
+
`cached_at` as 0 and deleted such a file.)
|
|
16
|
+
|
|
17
|
+
A caller with its own notion of "the same question" passes `key=`: the
|
|
18
|
+
entry is then keyed on that key plus the backend's identity and the tool,
|
|
19
|
+
not on the full prompt -- a diagnostic tool whose prompt carries changing
|
|
20
|
+
evidence can still reuse an answer for the same stable facts.
|
|
21
|
+
"""
|
|
22
|
+
from __future__ import annotations
|
|
23
|
+
|
|
24
|
+
import hashlib
|
|
25
|
+
import json
|
|
26
|
+
import os
|
|
27
|
+
import tempfile
|
|
28
|
+
import time
|
|
29
|
+
from pathlib import Path
|
|
30
|
+
from typing import Any
|
|
31
|
+
|
|
32
|
+
from .backend import Backend
|
|
33
|
+
from .types import Request, Response
|
|
34
|
+
|
|
35
|
+
CACHE_TTL_SECONDS = 24 * 60 * 60
|
|
36
|
+
CACHE_FORMAT = 1 # an entry without "format" reads as 1
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
def _now() -> float: # a seam for tests
|
|
40
|
+
return time.time()
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
def cache_key(backend: Backend, req: Request, extra: dict[str, Any] | None, tool: str,
|
|
44
|
+
key: str | None = None) -> str:
|
|
45
|
+
if key is not None:
|
|
46
|
+
payload = json.dumps({"identity": backend.identity, "key": key, "tool": tool}, sort_keys=True)
|
|
47
|
+
else:
|
|
48
|
+
payload = json.dumps({"identity": backend.identity, "request": req.fingerprint(),
|
|
49
|
+
"extra": extra or {}, "tool": tool}, sort_keys=True, default=str)
|
|
50
|
+
return hashlib.sha256(payload.encode("utf-8")).hexdigest()[:16]
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
def _path(cache_dir: Path, tool: str, backend: Backend, key: str) -> Path:
|
|
54
|
+
return Path(cache_dir) / f"{tool}_{backend.spec.name or backend.spec.transport}_{key}.json"
|
|
55
|
+
|
|
56
|
+
|
|
57
|
+
def _read(path: Path) -> dict | None:
|
|
58
|
+
try:
|
|
59
|
+
data = json.loads(path.read_text(encoding="utf-8"))
|
|
60
|
+
if int(data.get("format", 1)) != CACHE_FORMAT:
|
|
61
|
+
return None
|
|
62
|
+
if _now() - float(data.get("cached_at", 0)) > CACHE_TTL_SECONDS:
|
|
63
|
+
return None
|
|
64
|
+
resp = data.get("response")
|
|
65
|
+
if not isinstance(resp, dict) or not resp.get("text"):
|
|
66
|
+
return None
|
|
67
|
+
resp["cached_at"] = float(data["cached_at"])
|
|
68
|
+
return resp
|
|
69
|
+
except (OSError, ValueError, TypeError, KeyError):
|
|
70
|
+
return None
|
|
71
|
+
|
|
72
|
+
|
|
73
|
+
def _write(path: Path, backend: Backend, resp: Response) -> None:
|
|
74
|
+
try:
|
|
75
|
+
path.parent.mkdir(parents=True, exist_ok=True)
|
|
76
|
+
body = {"format": CACHE_FORMAT, "cached_at": _now(), "identity": backend.identity,
|
|
77
|
+
"response": {"text": resp.text, "model_used": resp.model_used,
|
|
78
|
+
"honoured": list(resp.honoured), "elapsed": resp.elapsed}}
|
|
79
|
+
# Atomic: a reader never sees half an entry (temp file, then os.replace;
|
|
80
|
+
# the idiom dazzle-filekit's atomic_write_text uses).
|
|
81
|
+
fd, tmp = tempfile.mkstemp(dir=str(path.parent), prefix=".tmp-", suffix=".json")
|
|
82
|
+
try:
|
|
83
|
+
with os.fdopen(fd, "w", encoding="utf-8") as fh:
|
|
84
|
+
fh.write(json.dumps(body, indent=1, default=str))
|
|
85
|
+
os.replace(tmp, path)
|
|
86
|
+
except OSError:
|
|
87
|
+
try:
|
|
88
|
+
os.unlink(tmp)
|
|
89
|
+
except OSError:
|
|
90
|
+
pass
|
|
91
|
+
raise
|
|
92
|
+
except OSError:
|
|
93
|
+
pass # a cache miss next time; not fatal
|
|
94
|
+
|
|
95
|
+
|
|
96
|
+
def _sweep(cache_dir: Path) -> None:
|
|
97
|
+
"""Remove stale cache entries -- and only cache entries: a JSON object
|
|
98
|
+
carrying a numeric `cached_at`. Anything else in the directory stays."""
|
|
99
|
+
cutoff = _now() - CACHE_TTL_SECONDS
|
|
100
|
+
try:
|
|
101
|
+
for p in Path(cache_dir).glob("*.json"):
|
|
102
|
+
try:
|
|
103
|
+
data = json.loads(p.read_text(encoding="utf-8"))
|
|
104
|
+
stamp = data.get("cached_at") if isinstance(data, dict) else None
|
|
105
|
+
if isinstance(stamp, (int, float)) and not isinstance(stamp, bool) and stamp < cutoff:
|
|
106
|
+
p.unlink()
|
|
107
|
+
except (OSError, ValueError, TypeError):
|
|
108
|
+
continue
|
|
109
|
+
except OSError:
|
|
110
|
+
pass
|
|
111
|
+
|
|
112
|
+
|
|
113
|
+
def run(backend: Backend, req: Request, *, cache_dir: Path | str,
|
|
114
|
+
fingerprint_extra: dict[str, Any] | None = None, refresh: bool = False,
|
|
115
|
+
tool: str = "ai", key: str | None = None) -> Response:
|
|
116
|
+
"""Ask `backend` for `req`, through the cache under `cache_dir`. `key`,
|
|
117
|
+
when given, replaces the prompt-derived key (see the module docstring)."""
|
|
118
|
+
cache_dir = Path(cache_dir)
|
|
119
|
+
key = cache_key(backend, req, fingerprint_extra, tool, key)
|
|
120
|
+
path = _path(cache_dir, tool, backend, key)
|
|
121
|
+
if not refresh:
|
|
122
|
+
hit = _read(path)
|
|
123
|
+
if hit:
|
|
124
|
+
return Response("answered", text=hit["text"], model_used=hit.get("model_used", ""),
|
|
125
|
+
honoured=tuple(hit.get("honoured", ())), elapsed=float(hit.get("elapsed", 0)),
|
|
126
|
+
cached=True, cached_at=hit["cached_at"], key=key)
|
|
127
|
+
resp = backend.invoke(req).with_(key=key)
|
|
128
|
+
if resp.status == "answered":
|
|
129
|
+
_write(path, backend, resp)
|
|
130
|
+
_sweep(cache_dir)
|
|
131
|
+
return resp
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
"""Readers a caller chooses from. The library never interprets an answer; it
|
|
2
|
+
offers two ways to read one and the caller picks the one its prompt asked
|
|
3
|
+
for. A merge tool wants one fenced JSON object; a diagnostic tool wants
|
|
4
|
+
labelled prose sections. Neither shape is this library's.
|
|
5
|
+
"""
|
|
6
|
+
from __future__ import annotations
|
|
7
|
+
|
|
8
|
+
import json
|
|
9
|
+
import re
|
|
10
|
+
from typing import Any
|
|
11
|
+
|
|
12
|
+
_FENCE = re.compile(r"```json\s*\n(.*?)\n\s*```", re.DOTALL)
|
|
13
|
+
|
|
14
|
+
#: The labelled-prose shape the original diagnostic tools ask for.
|
|
15
|
+
DEFAULT_SECTIONS: list[tuple[str, str]] = [
|
|
16
|
+
("what_happened", r"What Happened:"),
|
|
17
|
+
("why", r"Why:"),
|
|
18
|
+
("what_to_do", r"What To Do:"),
|
|
19
|
+
("confidence", r"Confidence:"),
|
|
20
|
+
]
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
def json_block(text: str) -> Any | None:
|
|
24
|
+
"""The LAST fenced ```json block in `text`, parsed; None when there is
|
|
25
|
+
none or it does not parse. The last one, because a model that thinks
|
|
26
|
+
aloud tends to draft and then answer."""
|
|
27
|
+
blocks = _FENCE.findall(text or "")
|
|
28
|
+
if not blocks:
|
|
29
|
+
return None
|
|
30
|
+
try:
|
|
31
|
+
return json.loads(blocks[-1])
|
|
32
|
+
except ValueError:
|
|
33
|
+
return None
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
def sections(text: str, labels: list[tuple[str, str]] | None = None) -> dict[str, str]:
|
|
37
|
+
"""Split labelled prose into a dict by the caller's labels -- each a
|
|
38
|
+
(key, regex) pair, in the order they appear. When nothing matches, the
|
|
39
|
+
whole text comes back under "raw", so a caller always has something to
|
|
40
|
+
show."""
|
|
41
|
+
labels = labels or DEFAULT_SECTIONS
|
|
42
|
+
out: dict[str, str] = {}
|
|
43
|
+
for i, (key, pattern) in enumerate(labels):
|
|
44
|
+
rest = [p for _, p in labels[i + 1:]]
|
|
45
|
+
regex = (rf"{pattern}\s*(.*?)(?=(?:{'|'.join(rest)})|\Z)" if rest
|
|
46
|
+
else rf"{pattern}\s*(.*)")
|
|
47
|
+
m = re.search(regex, text or "", re.DOTALL)
|
|
48
|
+
if m:
|
|
49
|
+
out[key] = m.group(1).strip()
|
|
50
|
+
if not out:
|
|
51
|
+
out["raw"] = (text or "").strip()
|
|
52
|
+
return out
|