Metadata-Version: 2.4
Name: bdp-insight
Version: 0.1.1
Summary: BDP-insight L2 HodgeConverter public prototype for output-prefix intervention experiments
Author: BDP Research
License: MIT License
        
        Copyright (c) 2026 BDP Research
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software for research, evaluation, and prototype integration purposes,
        including without limitation the rights to use, copy, modify, merge, publish,
        distribute, sublicense, and/or sell copies of the Software, subject to the
        following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        This package is a client-side research/debugging prototype. Access to paid
        server-side HodgeConverter functionality is governed separately by the relevant
        API Hub / RapidAPI plan, terms, and provider policies.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
        
Keywords: llm,debugger,interpretability,hodge,runtime-intervention
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: flask>=3.0.0
Provides-Extra: hf
Requires-Dist: torch; extra == "hf"
Requires-Dist: transformers; extra == "hf"
Provides-Extra: premium
Requires-Dist: requests>=2.31.0; extra == "premium"
Provides-Extra: studio
Requires-Dist: streamlit>=1.30; extra == "studio"
Requires-Dist: plotly>=5; extra == "studio"
Requires-Dist: pandas>=2; extra == "studio"
Requires-Dist: networkx>=3; extra == "studio"
Dynamic: license-file

# 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

```bash
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:

```python
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:

```text
X-RapidAPI-Key
X-RapidAPI-Host
```

No provider-side secrets are required in client code.

## Quick start

```bash
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

```bash
python example_interactive.py
```

or, after installation:

```bash
bdp-insight-chat
bdp-insight-smoke
bdp-insight-dashboard
bdp-insight-static
```

The interactive example can open:

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

Inside chat:

```text
/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`:

```json
{
  "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

```python
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

```text
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:

```text
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:

```bash
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:

```text
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.
