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

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.

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.

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.

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

# 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:

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

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