Metadata-Version: 2.5
Name: llmdbg
Version: 0.0.3a6
Summary: A debugger for stepping through LLM layers and interpreting internal representations.
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Debuggers
Requires-Python: >=3.10
Requires-Dist: gb10-load-llm==0.1.2
Requires-Dist: tomli>=2.0; python_version < '3.11'
Description-Content-Type: text/markdown

# llmdbg

`llmdbg` is an early-stage debugger for stepping through language-model layers
and presenting human-readable interpretations of internal vectors. It speaks
the [Debug Adapter Protocol](https://microsoft.github.io/debug-adapter-protocol/)
so editor integrations can use a standard debugger UI.

The current prototype includes real GPT-2 Small loading, layer-state capture,
logit-lens interpretations, and a VS Code debug extension. A deterministic
built-in trace remains available when no model is configured.

```console
pip install --pre llmdbg
llmdbg --version
```

## VS Code prototype

Build and install the extension:

```console
cd vscode-extension
npm install
npm run package
code --install-extension llmdbg-0.0.1.vsix
```

Create a `gpt2.llmdbg` file in the workspace:

```toml
[model]
id = "openai-community/gpt2"
revision = "main"
device = "cuda"
dtype = "bfloat16"

[input]
prompt = "The capital of France is"

[debug]
stop_on_entry = true

[[step]]
kind = "embedding"
path = "token_embedding"

[[step]]
kind = "attention"
path = "transformer.h.0.attention"

[[step]]
kind = "mlp"
path = "transformer.h.0.mlp"
```

Open that file and press **F5**. If VS Code asks for a debugger, choose
**llmdbg**. No `launch.json` is required. If a workspace launch configuration
is preferred, the complete minimal version is:

```json
{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "llmdbg",
      "request": "launch",
      "name": "llmdbg: Active file",
      "config": "${file}"
    }
  ]
}
```

On first use, the extension creates a private Python environment in VS Code's
extension storage. It does not install anything into the workspace. The first
GPT-2 run downloads and loads the model, then keeps its tensors resident in a
persistent model-host process. Stopping and restarting the debugger reuses the
resident model and runs only a new forward pass. Closing/reloading VS Code
stops the host and releases the model. Each `[[step]]` is an authored model
execution stop. Set breakpoints inside these tables or use **Step Over** to
advance through them. Runtime vectors appear in debugger scopes; the source
file is never rewritten.

To stop at a specific prompt token and layer, add a conditional breakpoint to
the desired `[[step]]` and use a zero-based condition such as
`token.position == 3`. The debugger prefills tokens before that position into
the KV cache, then captures the selected token with a one-token forward pass.
Stepping beyond the last selected layer advances to the next token using the
updated cache.

## License

MIT
