mimic-llm 0.1.0
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.
- checksums.yaml +7 -0
- data/LICENSE +21 -0
- data/NOTICE +16 -0
- data/README.md +175 -0
- data/exe/lllm +5 -0
- data/exe/llm +5 -0
- data/exe/mimic +5 -0
- data/lib/mimic/README.md +144 -0
- data/lib/mimic/agent/claude.rb +305 -0
- data/lib/mimic/agent/codex.rb +254 -0
- data/lib/mimic/agent/codex_fallback_prompt.md +275 -0
- data/lib/mimic/agent/hermes.rb +107 -0
- data/lib/mimic/agent/muse.rb +106 -0
- data/lib/mimic/agent.rb +46 -0
- data/lib/mimic/cli.rb +159 -0
- data/lib/mimic/client/base.rb +44 -0
- data/lib/mimic/client/crush.rb +28 -0
- data/lib/mimic/client/goose.rb +52 -0
- data/lib/mimic/client/hermes.rb +21 -0
- data/lib/mimic/client/opencode.rb +29 -0
- data/lib/mimic/client/pi.rb +50 -0
- data/lib/mimic/client.rb +19 -0
- data/lib/mimic/engine/README.md +140 -0
- data/lib/mimic/engine/base.rb +138 -0
- data/lib/mimic/engine/chat_template.rb +207 -0
- data/lib/mimic/engine/ik_llama.rb +273 -0
- data/lib/mimic/engine/launcher.rb +25 -0
- data/lib/mimic/engine/llama.rb +124 -0
- data/lib/mimic/engine/llama_embed.rb +108 -0
- data/lib/mimic/engine/router.rb +57 -0
- data/lib/mimic/engine/server_process.rb +108 -0
- data/lib/mimic/engine.rb +5 -0
- data/lib/mimic/engine_cli/binary_options.rb +46 -0
- data/lib/mimic/engine_cli/builder.rb +98 -0
- data/lib/mimic/engine_cli/diffusion.rb +117 -0
- data/lib/mimic/engine_cli/llama_preset.rb +119 -0
- data/lib/mimic/engine_cli/registry.rb +94 -0
- data/lib/mimic/engine_cli/source.rb +110 -0
- data/lib/mimic/engine_cli/status.rb +161 -0
- data/lib/mimic/engine_cli/update.rb +68 -0
- data/lib/mimic/engine_cli.rb +7 -0
- data/lib/mimic/health/checks.rb +92 -0
- data/lib/mimic/health.rb +82 -0
- data/lib/mimic/llm_cli/base.rb +36 -0
- data/lib/mimic/llm_cli/configure.rb +84 -0
- data/lib/mimic/llm_cli/embed.rb +80 -0
- data/lib/mimic/llm_cli/engines.rb +44 -0
- data/lib/mimic/llm_cli/models.rb +31 -0
- data/lib/mimic/llm_cli/models_table.rb +119 -0
- data/lib/mimic/llm_cli/paths.rb +48 -0
- data/lib/mimic/llm_cli/root.rb +215 -0
- data/lib/mimic/llm_cli/wizard/context_preflight.rb +82 -0
- data/lib/mimic/llm_cli/wizard/embed.rb +89 -0
- data/lib/mimic/llm_cli/wizard/moe.rb +82 -0
- data/lib/mimic/llm_cli/wizard/parallel.rb +76 -0
- data/lib/mimic/llm_cli/wizard/setup.rb +211 -0
- data/lib/mimic/llm_cli.rb +5 -0
- data/lib/mimic/llm_config/embed.rb +48 -0
- data/lib/mimic/llm_config/llama_settings.rb +60 -0
- data/lib/mimic/llm_config/model_settings.rb +84 -0
- data/lib/mimic/llm_config/sampling.rb +54 -0
- data/lib/mimic/llm_config/settings.rb +92 -0
- data/lib/mimic/llm_config.rb +132 -0
- data/lib/mimic/model/footprint.rb +303 -0
- data/lib/mimic/model/gguf.rb +204 -0
- data/lib/mimic/model/header.rb +169 -0
- data/lib/mimic/model/library.rb +132 -0
- data/lib/mimic/model/memory.rb +126 -0
- data/lib/mimic/model/store.rb +46 -0
- data/lib/mimic/model/upstream.rb +81 -0
- data/lib/mimic/model.rb +116 -0
- data/lib/mimic/paths.rb +45 -0
- data/lib/mimic/result.rb +8 -0
- data/lib/mimic/ui.rb +89 -0
- data/lib/mimic/util/fmt.rb +15 -0
- data/lib/mimic/util/hf.rb +55 -0
- data/lib/mimic/util/host.rb +95 -0
- data/lib/mimic/util/probes.rb +255 -0
- data/lib/mimic/version.rb +3 -0
- data/lib/mimic.rb +22 -0
- metadata +186 -0
checksums.yaml
ADDED
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
---
|
|
2
|
+
SHA256:
|
|
3
|
+
metadata.gz: 46e0ec34752f372cb8d8c07ab096ca407f27ba5e30abb6ee51cbef9ee24f579a
|
|
4
|
+
data.tar.gz: 499297fcc4dd6bbd42c65aebed77ee4e8f653f65946f209b4e0d71c692cdb043
|
|
5
|
+
SHA512:
|
|
6
|
+
metadata.gz: '08249511e1cf767cf2fa0b6592d58a4cf61e135020b4995cb09823b5364a22ac81dc6e887c3a0e6ef1f0b57aca290368dfc384fac0bd7cec1a0cb109bcc950d5'
|
|
7
|
+
data.tar.gz: 7167caab8a1a130640d6eb4aeed3eed7af8234e4119ff12d5eedb8bcc91cf0a337237d40a80dd6c741abe5416a20f08a66f416920d324048e216aa858e02aa5b
|
data/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 raykin
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
data/NOTICE
ADDED
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
mimic-llm bundles one file it did not write:
|
|
2
|
+
|
|
3
|
+
lib/mimic/agent/codex_fallback_prompt.md
|
|
4
|
+
|
|
5
|
+
It is a verbatim copy of the Codex CLI system prompt, taken from
|
|
6
|
+
unslothai/unsloth (unsloth_cli/codex_fallback_prompt.md), which in turn carries
|
|
7
|
+
it from OpenAI's Codex CLI. Both projects are licensed under the Apache License
|
|
8
|
+
2.0:
|
|
9
|
+
|
|
10
|
+
https://www.apache.org/licenses/LICENSE-2.0
|
|
11
|
+
|
|
12
|
+
The file is unmodified. `Mimic::Agent::Codex` reads it as the `base_instructions`
|
|
13
|
+
of the model catalog entry it writes for Codex, because a local llama.cpp server
|
|
14
|
+
has no hosted backend to supply them.
|
|
15
|
+
|
|
16
|
+
The rest of mimic-llm is MIT licensed -- see LICENSE.
|
data/README.md
ADDED
|
@@ -0,0 +1,175 @@
|
|
|
1
|
+
# mimic-llm
|
|
2
|
+
|
|
3
|
+
`llm` manages local llama.cpp, ik_llama.cpp, and PrismML llama.cpp servers. `mimic` launches Claude
|
|
4
|
+
Code or Codex against it, so a local model answers instead of a hosted one.
|
|
5
|
+
|
|
6
|
+
## Requirements
|
|
7
|
+
|
|
8
|
+
- **Linux**, **Ruby 3.2+**, and an NVIDIA or AMD GPU.
|
|
9
|
+
- **`claude` or `codex`** installed, for the launcher you want.
|
|
10
|
+
- Everything else -- the inference engine included -- `llm setup` handles.
|
|
11
|
+
|
|
12
|
+
## From nothing to a local Claude Code
|
|
13
|
+
|
|
14
|
+
gem install mimic-llm
|
|
15
|
+
|
|
16
|
+
Get one GGUF model file. This is the only step `llm` cannot do for you; it
|
|
17
|
+
downloads nothing. Any `.gguf` works, and unsloth publishes ready ones:
|
|
18
|
+
|
|
19
|
+
pip install huggingface_hub
|
|
20
|
+
hf download unsloth/Qwen3-Coder-30B-A3B-Instruct-GGUF \
|
|
21
|
+
--include "*UD-Q4_K_XL*" --local-dir ~/models
|
|
22
|
+
|
|
23
|
+
Then:
|
|
24
|
+
|
|
25
|
+
llm setup
|
|
26
|
+
|
|
27
|
+
It checks the box (RAM, disk, GPU backend, whether `llama-server` and `claude`
|
|
28
|
+
are already there), asks which engine to use, and **clones and builds it when no
|
|
29
|
+
binary exists** -- a CUDA build takes 10-30 minutes and needs `git`, `cmake`,
|
|
30
|
+
`cc`, `c++`. It then scans for GGUFs, and offers to type a path when it finds
|
|
31
|
+
none. Point it at `~/models`, or register the directory once with
|
|
32
|
+
`llm path add ~/models` so later runs list it.
|
|
33
|
+
|
|
34
|
+
The remaining steps pick a context length and whether the model thinks before
|
|
35
|
+
answering. Context is checked against your card's free VRAM before it is
|
|
36
|
+
accepted, so an oversized choice is rejected at the prompt rather than at a
|
|
37
|
+
failed launch. Settings land in `~/.llm/config.yaml`, and setup offers to start
|
|
38
|
+
the server.
|
|
39
|
+
|
|
40
|
+
llm status
|
|
41
|
+
|
|
42
|
+
Confirms the server is up, on `http://127.0.0.1:8080` by default, and prints
|
|
43
|
+
what it loaded. Then:
|
|
44
|
+
|
|
45
|
+
mimic claude
|
|
46
|
+
|
|
47
|
+
Claude Code, answered by your own model. `mimic codex` does the same for Codex.
|
|
48
|
+
|
|
49
|
+
To change anything later: `llm setup` again, or `llm config` for one value,
|
|
50
|
+
then `llm restart`.
|
|
51
|
+
|
|
52
|
+
`llm engines` lists all three engines with their source, branch, checkout,
|
|
53
|
+
revision, and binary. `llm engines update` fetches all three and rebuilds any
|
|
54
|
+
that are behind; restart the server to use a rebuilt binary.
|
|
55
|
+
|
|
56
|
+
If something else already owns `llm` on your `PATH` (the python `llm` CLI, most
|
|
57
|
+
often), the gem installs `lllm` as the same program under a free name.
|
|
58
|
+
|
|
59
|
+
## State it owns
|
|
60
|
+
|
|
61
|
+
| Path | Contents |
|
|
62
|
+
| --- | --- |
|
|
63
|
+
| `~/.llm` | engine side: `config.yaml`, checkouts, presets, chat templates, sidecar stores, `run/` (logs, launch records) |
|
|
64
|
+
| `~/.mimic` | agent side: isolated agent homes under `agents/`, the `bin/` PATH shim, `mcp-servers.json` |
|
|
65
|
+
| `/tmp/llm` | pid files for the running servers |
|
|
66
|
+
|
|
67
|
+
Neither engine claims a home directory of its own, so `~/.llm` is this gem's to
|
|
68
|
+
define.
|
|
69
|
+
|
|
70
|
+
## Paths it assumes rather than discovers
|
|
71
|
+
|
|
72
|
+
These are hardcoded. Nothing probes for them, and nothing errors when they are
|
|
73
|
+
absent — the feature that depends on one silently finds nothing.
|
|
74
|
+
|
|
75
|
+
**Models.** The default search paths are `~/hf-models`, `~/.llm/models` and
|
|
76
|
+
`~/.lmstudio/models`. Add your own with `llm path add DIR`; the list lives in
|
|
77
|
+
`~/.llm/config.yaml` and the defaults are only the starting point.
|
|
78
|
+
`Model::Upstream` also treats `~/.lmstudio/models` as the layout that names a
|
|
79
|
+
model's source repo, so `llm models check` reports `?` for models stored any
|
|
80
|
+
other way whose GGUF header names no repo either.
|
|
81
|
+
|
|
82
|
+
**Engine binary.** Each engine has its own ordered resolution list — for
|
|
83
|
+
llama.cpp: `llama-server` on `PATH`, then its checkout at
|
|
84
|
+
`~/.llm/llama.cpp/build/bin/llama-server`, then `~/.local/bin/llama-server`.
|
|
85
|
+
ik_llama.cpp prefers its own build over `PATH`. The current
|
|
86
|
+
`prism-v7-llama.cpp` accepts only its own build, since its ternary formats
|
|
87
|
+
need Prism kernels. `llm setup` clones and builds into `~/.llm`.
|
|
88
|
+
|
|
89
|
+
**Client configs.** `llm sync` pushes the active model alias and context length
|
|
90
|
+
into whichever of these already exist, and skips the rest:
|
|
91
|
+
|
|
92
|
+
| Client | File |
|
|
93
|
+
| --- | --- |
|
|
94
|
+
| crush | `~/.config/crush/crush.json` |
|
|
95
|
+
| opencode | `~/.config/opencode/opencode.jsonc` |
|
|
96
|
+
| goose | `~/.config/goose/config.yaml` (+ `custom_providers/llamacpp.json`) |
|
|
97
|
+
| pi | `~/.pi/agent/models.json`, `settings.json` |
|
|
98
|
+
| hermes | `~/.hermes/config.yaml` |
|
|
99
|
+
|
|
100
|
+
An existing config file is the only evidence a client is installed — goose in
|
|
101
|
+
particular gets nothing written unless its config is already there. `opencode`
|
|
102
|
+
is skipped, with a warning, when its `.jsonc` carries comments, since rewriting
|
|
103
|
+
it as JSON would drop them.
|
|
104
|
+
|
|
105
|
+
**Agent binaries.** `mimic claude` and `mimic codex` resolve `claude` and
|
|
106
|
+
`codex` on `PATH` and abort with an install hint when either is missing
|
|
107
|
+
(`MIMIC_ALLOW_INSTALL=1` lets codex through so its own installer can run).
|
|
108
|
+
`mimic hermes-lcc` wants `hermes`, which `mimic install-hermes` puts in an
|
|
109
|
+
isolated venv at `~/.hermes/venv`. All three also require llama-server to be
|
|
110
|
+
up, and say so rather than failing at the first request.
|
|
111
|
+
|
|
112
|
+
## MCP servers (opt-in)
|
|
113
|
+
|
|
114
|
+
`mimic claude` runs Claude Code against a config dir of its own, and wires in
|
|
115
|
+
whatever `~/.mimic/mcp-servers.json` names — Claude Code's own `mcpServers`
|
|
116
|
+
shape, merged into that dir's `.claude.json` without touching entries you added
|
|
117
|
+
by hand:
|
|
118
|
+
|
|
119
|
+
```json
|
|
120
|
+
{
|
|
121
|
+
"c4ai": { "command": "python", "args": ["-m", "c4ai_mcp.fastmcp_server"] }
|
|
122
|
+
}
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
No file means no servers. The gem ships none and picks none for you.
|
|
126
|
+
|
|
127
|
+
`WebSearch` and `WebFetch` are denied regardless. They are Anthropic
|
|
128
|
+
server-executed tools; llama.cpp's `/v1/messages` bridge has no implementation
|
|
129
|
+
(`unsupported Responses tool type 'web_search'` in the server log) and returns
|
|
130
|
+
zero results rather than failing. Denying them makes that visible. An MCP server
|
|
131
|
+
is how you give the model internet access instead. Whatever you name has to be
|
|
132
|
+
runnable on its own — nothing in the example above ships with this gem.
|
|
133
|
+
|
|
134
|
+
## Development
|
|
135
|
+
|
|
136
|
+
```
|
|
137
|
+
bundle install && bundle exec rspec < /dev/null
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
The `< /dev/null` is required: one spec exercises cli-ui's prompt layer, which
|
|
141
|
+
opens Reline against the terminal and blocks forever when stdin is a tty.
|
|
142
|
+
|
|
143
|
+
To run a checkout instead of the installed gem, symlink `exe/llm` and
|
|
144
|
+
`exe/mimic` onto your `PATH` -- they run under plain `ruby`, so the gem
|
|
145
|
+
dependencies have to be on the default gem path.
|
|
146
|
+
|
|
147
|
+
The suite runs under `spec/support/real_llm_root_guard.rb`, which raises on any
|
|
148
|
+
write or delete under `~/.llm`, `~/.mimic`, `/tmp/llm` or a client config tree.
|
|
149
|
+
Point a `stub_const` at a tmpdir instead.
|
|
150
|
+
|
|
151
|
+
## Trademarks
|
|
152
|
+
|
|
153
|
+
Not affiliated with, endorsed by, or sponsored by Anthropic, OpenAI or unsloth.
|
|
154
|
+
"Claude", "Claude Code", "Codex" and "OpenAI" are trademarks of their respective
|
|
155
|
+
owners, used here only to describe what this tool interoperates with.
|
|
156
|
+
|
|
157
|
+
This project ships neither client. `mimic` launches `claude` or `codex` if you
|
|
158
|
+
have installed them yourself, and configures them through their own documented
|
|
159
|
+
settings -- `ANTHROPIC_BASE_URL` for Claude Code, `model_providers` for Codex.
|
|
160
|
+
No Anthropic or OpenAI credential is used or required; `Agent::Claude` unsets
|
|
161
|
+
`ANTHROPIC_API_KEY` and `CLAUDE_CODE_OAUTH_TOKEN` before launching. Your use of
|
|
162
|
+
either client remains governed by its own license and terms.
|
|
163
|
+
|
|
164
|
+
Design credit: the Claude Code and Codex launch recipes are reimplementations of
|
|
165
|
+
[unsloth](https://github.com/unslothai/unsloth)'s `unsloth_cli/start.py`. What
|
|
166
|
+
was taken and what was deliberately left is recorded in `UPSTREAM-REVIEW.md`.
|
|
167
|
+
The Codex provider block mimic writes still carries unsloth's own profile name
|
|
168
|
+
(`unsloth_api`) and auth env var, so an existing `~/.codex/config.toml` keeps
|
|
169
|
+
working.
|
|
170
|
+
|
|
171
|
+
## License
|
|
172
|
+
|
|
173
|
+
MIT -- see [LICENSE](LICENSE). One bundled file is not MIT:
|
|
174
|
+
`lib/mimic/agent/codex_fallback_prompt.md` is a verbatim Apache-2.0 copy of the
|
|
175
|
+
Codex CLI system prompt, carried from unsloth. See [NOTICE](NOTICE).
|
data/exe/lllm
ADDED
data/exe/llm
ADDED
data/exe/mimic
ADDED
data/lib/mimic/README.md
ADDED
|
@@ -0,0 +1,144 @@
|
|
|
1
|
+
# Mimic — design rules and traps
|
|
2
|
+
|
|
3
|
+
Conventions the whole library is written to, and the mistakes it has already
|
|
4
|
+
made. `engine/README.md` covers the engine namespaces specifically.
|
|
5
|
+
|
|
6
|
+
## Design rules
|
|
7
|
+
|
|
8
|
+
- **Objects, not modules of free functions.** If the same argument is threaded
|
|
9
|
+
through most functions in a file (`cfg`, `client`, `path`), that argument is
|
|
10
|
+
the object: make it a class, take it in `initialize`, drop it from every
|
|
11
|
+
signature. A helper module is for genuinely stateless helpers with no shared
|
|
12
|
+
subject — these live under `Mimic::Util` (`Util::Fmt`, `Util::Probes`,
|
|
13
|
+
`Util::Host`).
|
|
14
|
+
- **`module_function` is banned; use `class << self`.** Under `module_function`
|
|
15
|
+
a plain `private` does not touch the singleton methods callers actually
|
|
16
|
+
reach, so "every class declares its private surface" is unexpressible. It is
|
|
17
|
+
also a mode switch — a method below the macro silently becomes a module
|
|
18
|
+
function, one above silently does not — and it leaves a private
|
|
19
|
+
instance-method twin of everything that an `include` would inject.
|
|
20
|
+
- **`cfg` belongs in an ivar**, set once in `initialize`, not recomputed at
|
|
21
|
+
every call site or passed down a call chain.
|
|
22
|
+
- **Config is read through its section object, never a flat accessor on
|
|
23
|
+
`Settings`.** `Settings` exposes `model`, `llama` and `embed` mirroring the
|
|
24
|
+
YAML sections: `cfg.model.context_length`, `cfg.llama.port`,
|
|
25
|
+
`cfg.model.sampling`. `cfg.model.file` is the `Mimic::Model` for the
|
|
26
|
+
configured path, rebuilt when the path changes. A `cfg.port`-style delegator
|
|
27
|
+
rebuilds the 28-method flat surface this replaced; put the accessor on the
|
|
28
|
+
section that owns the key.
|
|
29
|
+
- **A section object reads through `section` and writes through `writable`.**
|
|
30
|
+
An absent section reads as an empty hash and only a write materialises it, so
|
|
31
|
+
a partial config keeps exactly the sections it carries. Never rebuild a
|
|
32
|
+
section hash from known keys — `~/.llm/config.yaml` carries keys no accessor
|
|
33
|
+
knows about (`model.backend`) and `save` has to preserve them.
|
|
34
|
+
- **`Settings#save` writes `@cfg.slice("model", "llama", "embed")` and nothing
|
|
35
|
+
else.** A hand-added top-level key is dropped on the next save. All writers
|
|
36
|
+
(`llm setup`, `llm path`, `llm config`, `llm embed`) agree on this; don't
|
|
37
|
+
reintroduce a full-hash write for one of them.
|
|
38
|
+
- **All terminal output goes through `Mimic::Ui`.**
|
|
39
|
+
`Ui.green/red/yellow/cyan/gray/bold`, `Ui.banner/panel/table` and
|
|
40
|
+
`Ui::Prompt` (`select`/`ask`/`yes?`) are the whole surface; nothing else names
|
|
41
|
+
`CLI::UI`. The TTY toolkit was swapped out in 2026-08 after five years without
|
|
42
|
+
a release, and the point of the boundary is that the next swap is one file.
|
|
43
|
+
`Ui::Prompt` stays an injected collaborator (`prompt:` kwarg) rather than a
|
|
44
|
+
module call so wizard specs keep a seam that isn't a global stub.
|
|
45
|
+
- **A namespace directory may require its parent back.**
|
|
46
|
+
`llm_config/{settings,model_settings,embed}.rb` each `require_relative
|
|
47
|
+
"../llm_config"` and are required from it in turn. The cycle is harmless
|
|
48
|
+
because every cross-reference (`Embed#model_alias` → `Settings.alias_for`,
|
|
49
|
+
`Settings#model` → `ModelSettings`) resolves at call time. A load-time
|
|
50
|
+
reference across that seam — a superclass, an `include`, a constant in a
|
|
51
|
+
default argument — is what breaks it. Only `mimic`, `mimic/llm_config`,
|
|
52
|
+
`mimic/model` and `agent/hermes` are real entry points; that the
|
|
53
|
+
`llm_config/*` files load standalone is checked by hand after a move, not by
|
|
54
|
+
a spec.
|
|
55
|
+
- **Symbol keys inside the app, string keys only at the YAML/JSON boundary.**
|
|
56
|
+
Config parsed off disk is string-keyed because that is what the format gives
|
|
57
|
+
you; anything constructed and consumed purely in Ruby stays symbol-keyed.
|
|
58
|
+
|
|
59
|
+
## Ruby traps this port has already fallen into
|
|
60
|
+
|
|
61
|
+
- **`raise SystemExit, "message"` exits 0 and prints nothing.** A String is a
|
|
62
|
+
_message_; status stays 0 and Ruby prints nothing for an uncaught
|
|
63
|
+
`SystemExit`. Five sites shipped this way. Use `abort "msg"` (stderr, exit 1).
|
|
64
|
+
`raise SystemExit, <Integer>` is fine.
|
|
65
|
+
- **Moving a file into a namespace can silently repoint its bare constants.**
|
|
66
|
+
`Mimic::LlmCli::Paths` is a Thor subcommand, so a file moved under `LlmCli`
|
|
67
|
+
resolves bare `Paths::LLM_ROOT` to it and dies with `uninitialized constant` —
|
|
68
|
+
lexical lookup checks the enclosing namespace before `Mimic`. After such a
|
|
69
|
+
move, grep the moved file for bare references to its new siblings' names and
|
|
70
|
+
qualify them (`Mimic::Paths::…`).
|
|
71
|
+
- **A class named for a core Ruby constant shadows it namespace-wide.**
|
|
72
|
+
`Engine::Process` made `Launcher`'s `Process.spawn` resolve to the new class.
|
|
73
|
+
The whole `Engine` tree was affected, not just the defining file. Hence
|
|
74
|
+
`Engine::ServerProcess`.
|
|
75
|
+
- **`reline` and `readline` are not default gems on Ruby 4.0.** cli-ui's
|
|
76
|
+
`prompt.rb` requires both at load and dies with `cannot load such file --
|
|
77
|
+
readline`. `reline` is an explicit gemspec dependency; do not "clean up" that
|
|
78
|
+
seemingly-stdlib entry.
|
|
79
|
+
- **cli-ui's own `Table` renders through `CLI::UI.puts`, which hard-wraps.**
|
|
80
|
+
Both `puts_table` and `capture_table` fold a wide board into fragments at the
|
|
81
|
+
terminal width. `Ui.table` pads columns itself and measures with
|
|
82
|
+
`CLI::UI::ANSI.printing_width` so colour escapes don't count.
|
|
83
|
+
- **Narrow `rescue` clauses swallow less than they look like they do.**
|
|
84
|
+
`rescue Errno::ENOENT` covers one errno; an unreadable file took down all of
|
|
85
|
+
`llm sync` because the real failure was a different errno. Prefer
|
|
86
|
+
`SystemCallError`, and `Psych::Exception` over `Psych::SyntaxError`.
|
|
87
|
+
`Psych.safe_load` needs `permitted_classes: [Symbol, Date, Time]`.
|
|
88
|
+
- **A raise inside a per-client/per-model loop kills the whole run.** Return
|
|
89
|
+
`nil`/`false` from the helper and let the loop continue past one bad entry.
|
|
90
|
+
- **`IO#seek` issues a real `lseek(2)` every call.** A line-for-line seek loop
|
|
91
|
+
can be ~5× slower than it looks — see
|
|
92
|
+
`docs/llm-models-query-performance-issue.md`.
|
|
93
|
+
- **`expand_path` does not resolve symlinks.** `~/hf-models` is a tree of
|
|
94
|
+
per-file symlinks into their `.lmstudio` targets, and anything keyed by model
|
|
95
|
+
path has to resolve through them or it splits into two disagreeing key sets
|
|
96
|
+
(this happened to `~/.llm/model-ctx.json`). Model paths go through
|
|
97
|
+
`LlmConfig.resolve_path`, and `select_model` returns a `realpath`.
|
|
98
|
+
- **A stub only covers the constant the call site actually names.**
|
|
99
|
+
`ik_llama.rb` calls `Base.cleanup_failed(pid)` and `Base.last_lines(tail)`
|
|
100
|
+
literally, not through `self.class`, so `allow(described_class)` — or worse a
|
|
101
|
+
sibling — stubs nothing and the real method runs. That shipped: the ik
|
|
102
|
+
retry-loop specs deleted the live `/tmp/llm/llama-server.pid` on every suite
|
|
103
|
+
run and `llm status` reported `(pid ?)` for a server that was up. Read the
|
|
104
|
+
call site before choosing the stub target; a passing suite does not prove the
|
|
105
|
+
stub bound.
|
|
106
|
+
- **Thor**: `def self.exit_on_failure? = true` must stay, or error paths print a
|
|
107
|
+
deprecation warning and exit 0.
|
|
108
|
+
|
|
109
|
+
## Scope boundaries
|
|
110
|
+
|
|
111
|
+
- `agent.rb`'s Unsloth-replacement launchers are **claude and codex only**.
|
|
112
|
+
Upstream ships six agents; the other four were cut on purpose. Don't add them
|
|
113
|
+
back. `Agent::Hermes` is not one of them — Hermes is mimic's own agent and
|
|
114
|
+
owns the `~/.hermes` tree (venv, config, logs, state DB).
|
|
115
|
+
- **One file is vendored from upstream unsloth, and only one.**
|
|
116
|
+
`agent/codex_fallback_prompt.md` is a byte-identical copy of
|
|
117
|
+
`unsloth_cli/codex_fallback_prompt.md`, carrying OpenAI's Codex CLI system
|
|
118
|
+
prompt — both Apache-2.0, recorded in `NOTICE`, packaged by the gemspec's
|
|
119
|
+
`lib/**/*` glob. Keep it verbatim: modifying it puts the Apache-2.0 4(b)
|
|
120
|
+
change-notice obligation on us and makes upstream diffs meaningless. Nothing
|
|
121
|
+
else is vendored — `Agent::Claude` / `Agent::Codex` reimplement unsloth's
|
|
122
|
+
launch recipe, and `../unsloth/` is a reference checkout, not a runtime
|
|
123
|
+
dependency. Reviewing upstream for changes worth reimplementing is a periodic
|
|
124
|
+
judgement pass, run from this machine's `/sync-unsloth-cc-codex` against an untracked
|
|
125
|
+
`UPSTREAM-REVIEW.md` ledger.
|
|
126
|
+
- **`Engine::LlamaEmbed` is selected by role, never by config, so it must stay
|
|
127
|
+
out of `EngineCli::Registry::ENGINES`.** `Registry.for(settings)` dispatches
|
|
128
|
+
on `cfg.llama.engine` and `Registry.names` drives the setup wizard's engine
|
|
129
|
+
picker (`llm_cli/wizard/setup.rb:70`, pinned by
|
|
130
|
+
`spec/llm_cli/wizard/setup_spec.rb:43`); an entry there would offer the
|
|
131
|
+
embedding server as a chat engine. The eight chat-only private methods it
|
|
132
|
+
inherits and never calls were the accepted price of `Base` already being
|
|
133
|
+
abstract, not an oversight to tidy.
|
|
134
|
+
- **`llm setup` is the only setup wizard.** `mimic` had a second one that
|
|
135
|
+
duplicated its six engine/model steps; it was never a command, only a
|
|
136
|
+
no-config fallback, and it went in 2026-08. `mimic` now aborts with "run `llm
|
|
137
|
+
setup` first". The one thing it did that `llm setup` does not is
|
|
138
|
+
`Agent::Hermes.install`, which survives behind `mimic install-hermes`. Don't
|
|
139
|
+
reintroduce a `mimic setup`.
|
|
140
|
+
- **`mimic` owns no config of its own.** It reads `~/.llm/config.yaml` and
|
|
141
|
+
writes other tools' files. Resist adding a settings layer — one was deleted in
|
|
142
|
+
2026-07 for being dead weight, and the `Mimic::Config` shim that outlived it
|
|
143
|
+
went in 2026-08. Read config through `LlmConfig`; a path another tool owns
|
|
144
|
+
belongs on that tool's own module.
|