neurobyte 0.2.3
Export Jupyter notebooks into narrated, cell-labeled text.
License: MIT
Requires Python: >=3.9

# Neurobyte
### by Allostan Labs

**Neurobyte** is a developer tool designed to optimize Jupyter Notebooks for AI-driven development. It acts as a middleware between your messy experimental notebooks and your LLM's context window.

By sanitizing, auditing, and formatting your code *before* you paste it into an LLM (or send it via API), you reduce hallucinations, save context tokens, and improve the quality of generated code.

## Why Neurobyte?

*   **Reduce Noise**: Strip magic commands (`%sql`, `!pip`), progress bars, and massive outputs that confuse models using `neurobyte export --clean`.
*   **Prevent Errors**: Audit your notebook for non-reproducible patterns (absolute paths, hidden states) before asking an AI to refactor it.
*   **Optimize Context**: Hoist imports to the top and format code with `ruff` so the LLM parses dependencies immediately.

---

## Installation

```bash
pip install neurobyte
# OR
pip install "neurobyte[all]"
```

## Core Workflow

Neurobyte follows a **Audit → Format → Export** workflow to ensure high-quality context.

### 1. Audit: Health Checks for Notebooks

The `audit` command analyzes your notebook for issues that typically degrade LLM performance or cause hallucinated fixes.

```bash
neurobyte audit my_notebook.ipynb
```

**What it checks:**
*   **Reproducibility**: Flags `!pip install` and hardcoded absolute paths (`/Users/pedro/...`).
*   **Cyclomatic Complexity**: Identifies "spaghetti code" cells (complexity > 10) that should be refactored before asking for changes.
*   **Execution Order**: Warns if cells were run out of order (e.g., cell 10 run before cell 5), which creates hidden state bugs.
*   **Secrets**: Scans for potential leaked API keys (`api_key="sk-..."`).
*   **Output Size**: Flags cells with massive text outputs (>5000 chars) that waste tokens.

### 2. Format: Token Optimization

The `format` command standardizes your code to make it easier for models to understand.

```bash
neurobyte format my_notebook.ipynb --hoist
```

**Features:**
*   **Ruff formatting**: Applies standard Python formatting to all code cells.
*   **Import Hoisting (`--hoist`)**: Extracts all `import` statements from scattered cells and consolidates them into a single top-level "Setup" cell.
    *   *Why?* LLMs perform better when they see dependencies upfront.

### 3. Export: Context Preparation

The `export` command is the final step. It converts your notebook into an LLM-ready text representation.

```bash
neurobyte export my_notebook.ipynb --output-format xml
```

#### Options

*   **Output Formats**:
    *   `txt` (default): Minimalist representation, distinct headers.
    *   `xml`: Structured format (`<cell>...`) ideal for Claude/Anthropic prompts.
    *   `json`: Full metadata preservation.

*   **Cleaning features**:
    *   `--strip-magics`: Removes IPython specific syntax (`%timeit`, `!ls`) that causes syntax errors in standard Python scripts.
    *   `--clear-output`: Removes all graph/text outputs. Useful when you only want the *code* logic reviewed.
    *   `--redact-secrets`: Automatically replaces API keys with `[REDACTED]`.

*   **Selective Export**:
    *   `--include-markdown`: Include documentation text.
    *   `--max-cells 50`: Limit context size.

#### Example: The "Perfect Context" Pipeline

```bash
# 1. Clean up the code structure
neurobyte format analysis.ipynb --hoist

# 2. Check for issues
neurobyte audit analysis.ipynb

# 3. Export a clean, code-only version for your prompt
neurobyte export analysis.ipynb \
    --strip-magics \
    --clear-output \
    --output-format xml \
    --outfile context.xml
```

---

## Configuration

You can persist your preferences in `pyproject.toml`:

```toml
[tool.neurobyte]
redact_secrets = true
extra_redact_patterns = [
    "internal_project_id",
]

[tool.neurobyte.export]
output_format = "xml"
strip_magics = true
include_markdown = false
```