BDP-insight L2 HodgeConverter v0.1.1

BDP-insight L2 HodgeConverter is a public prototype for controlled output-prefix intervention through an API Hub / Modal server-bound Hodge kernel.

It is not ordinary prompt rewriting. The original user prompt remains unchanged. In the full debugger workflow, a local model begins generation, the debugger observes partial assistant output, a selected target span is sent to the server-bound Hodge kernel, and continuation resumes from the patched prefix.

This is a research/debugging prototype. It does not guarantee arithmetic correctness, universal reasoning improvement, full hidden-state control, or proof of tensor causality.

Install

pip install -e .
pip install -e ".[hf]"
pip install -e ".[hf,studio]"

Required API Hub values

Copy these from your RapidAPI / API Hub Code Snippet:

rapidapi_url = "https://bdp-insight-l2.p.rapidapi.com/v1/hodge/convert"
rapidapi_host = "bdp-insight-l2.p.rapidapi.com"
rapidapi_key = "YOUR_RAPIDAPI_KEY"

Client code needs only:

X-RapidAPI-Key
X-RapidAPI-Host

No provider-side secrets are required in client code.

Quick start

python example_run.py                 # minimal Qwen dynamic debugger example
python example_interactive.py         # guided chat + optional dashboards
python examples/example_direct_api.py # API Hub / Modal smoke test only

Interactive chat and dashboards

python example_interactive.py

or, after installation:

bdp-insight-chat
bdp-insight-smoke
bdp-insight-dashboard
bdp-insight-static

The interactive example can open:

Dynamic debugger: http://127.0.0.1:7860
Static Studio:    http://127.0.0.1:8501

Inside chat:

/hodge 9 2 8 32
/max 256
/quit

Direct API Hub smoke test

The API Hub endpoint is a Hodge conversion component. It is not a remote full-model generation endpoint.

Example request body for /v1/hodge/convert:

{
  "text": "2 + 4 = 6",
  "replacement": "9",
  "target_regex": "(?<=\\+)\\s*\\d+",
  "mode": "output"
}

The full Python debugger workflow is demonstrated by example_run.py and example_interactive.py.

Use in your own code

from bdp_insight.api import (
    BDPHodgeConfig,
    attach_hodge_debugger,
    queue_hodge_output_intervention,
)

config = BDPHodgeConfig(
    rapidapi_url="https://bdp-insight-l2.p.rapidapi.com/v1/hodge/convert",
    rapidapi_host="bdp-insight-l2.p.rapidapi.com",
    rapidapi_key="YOUR_RAPIDAPI_KEY",
)

model = attach_hodge_debugger(
    model=model,
    tokenizer=tokenizer,
    config=config,
    model_id="your-model",
    run_dir="results/bdp_hodge_run",
)

queue_hodge_output_intervention(
    run_dir="results/bdp_hodge_run",
    new_word="9",
    target_regex="2",
    wait_tokens=8,
    continuation_tokens=32,
)

# Then call model.generate(...) normally.

File layout

example_run.py                 # main copy/paste minimal user example
example_interactive.py         # guided chat + optional dashboards
bdp_insight/api.py             # public Python wrapper
bdp_insight/cli.py             # console script entry points
bdp_insight/launchers.py       # dashboard process launch helpers
examples/example_direct_api.py # API Hub smoke test
examples/example_gemma.py      # optional Gemma-style example

Static Studio / IRS-DCE capture

Static Studio's IRS-DCE Dynamics tab needs capture runs containing:

result_minimal.json["hidden_states_per_layer"]

This package enables hidden-state capture by default when using attach_hodge_debugger(...), example_run.py, or example_interactive.py.

To disable the extra hidden-state forward pass in the interactive CLI:

bdp-insight-chat --no-capture

Prototype caveats

• This is a research/debugging prototype.
• Intervention effects depend on model, language, response template, target regex, wait timing, and continuation length.
• Target-level interventions require the target to appear in generated partial output.
• Small local models may still fail arithmetic after a successful intervention.
• Qwen/Qwen2.5-0.5B-Instruct is the public baseline example model.
• Gemma-style structured outputs can expose a wider intervention surface, but this is an observational compatibility note, not a guarantee.

Privacy notice

L2 HodgeConverter may transmit prompt/token observations or partial generated output to the paid server-bound kernel for runtime patch preparation. Do not submit secrets, credentials, personal data, private datasets, or confidential production prompts.

BDP does not intentionally persist raw prompts or raw generated text; request payloads are discarded after the operation. Operational logs should be limited to request IDs, timestamps, status, usage counters, lengths, hashes, and plan metadata.

Troubleshooting interactive input

If you see:

unknown url type: 'y/v1/hodge/convert'

then y was typed at the RapidAPI URL prompt. Press Enter at URL/Host prompts to use defaults. The dashboard y/N questions appear after API config is accepted.