Skip to content

README.md

Latest commit

 

History

History
342 lines (263 loc) · 12.8 KB

README.md

File metadata and controls

342 lines (263 loc) · 12.8 KB

📓 Code Notebook — AI-Powered Code Explainer

Python Streamlit LangChain LangGraph License

Upload any code file → AI automatically splits it into logical blocks → Displays as an interactive Notebook with explanations and difficulty ratings

Features · Quick Start · Switching AI Providers · Project Structure · Roadmap

✨ Features

🧠 AI Analysis

  • Structured LLM output via Pydantic models — cells are always well-formed, never free-form text
  • Smart code chunking — boundary-aware splitting for files over 8,000 characters; each chunk analyzed independently and merged seamlessly
  • Per-block difficulty rating — LLM scores each cell 1 (easy) / 2 (medium) / 3 (complex), visualized as colored dots
  • Whole-file summary — 3–5 sentence architectural overview generated after cell analysis
  • Automatic comment stripping — pre-processing removes comments before sending to LLM, reducing token usage and improving signal quality
  • Multi-block error recovery — a failed chunk inserts an error placeholder instead of aborting the entire analysis
  • Retry logic — exponential backoff (up to 2 retries) on LLM failures
  • Single-cell follow-up Q&A — select any cell and ask the AI a targeted question about it

🎨 Rendering & UI

  • Tokyo Night dark theme — unified color palette across all components (header, code, explanation, summary)
  • Carbon-style cell headers — macOS traffic-light dots, colored left border per cell type, type badge
  • Syntax highlighting — highlight.js atom-one-dark theme with line numbers via highlightjs-line-numbers.js
  • Collapsible cells — click ⌄ on any cell header to collapse/expand; button label updates accordingly
  • One-click code copy — ⎘ button per cell, with clipboard fallback for older browsers, flashes ✓ on success
  • Sticky search bar — real-time client-side search across title, type, explanation and code preview; shows match count and a ✕ clear button
  • Skeleton loading screen — shimmer placeholder cards shown while the LLM processes, eliminates blank-page waiting
  • Streaming summary output — summary text streams token-by-token into the UI with a blinking cursor
  • iframe height auto-adapt — ResizeObserver + postMessage reports real content height to Streamlit, eliminating scrollbars and empty space

📁 File Support

Supports 60+ languages across 10 categories:

Category Extensions
Web .html .css .scss .js .ts .vue
Systems .c .cpp .cs .rs .go .zig
JVM .java .kt .scala .groovy
Scripting .py .rb .php .lua .jl .pl
Shell .sh .bash .zsh .ps1 .bat
Mobile .swift .dart .m
Data / Query .sql .graphql .proto
Config .yaml .toml .xml .tf .ini
Functional .hs .ex .erl .clj .ml .fs
Other .r .vb .asm .nim .md

🗂️ History & Export

  • Persistent JSON history — every analysis saved with filename, language, line count, char count, cell count, elapsed time, timestamp, summary and full cell data
  • History sidebar — browse last 20 analyses; load or delete individually, or clear all at once
  • Return-to-home button — one click to reset state without page refresh
  • Markdown export — download the entire notebook as a structured .md file with fenced code blocks, emoji headers and difficulty stars

⚙️ Model Selection

Switch between models from the sidebar without restarting:

  • DeepSeek Chat — general-purpose, best for mixed-language files
  • DeepSeek Coder — code-specialized model, higher accuracy on logic-heavy files

🚀 Quick Start

Prerequisites

Installation

git clone https://github.com/yourname/code-notebook.git
cd code-notebook

python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate

pip install -r requirements.txt

Environment Setup

Create a .env file in the project root:

DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx

Run

streamlit run app.py

Open http://localhost:8501 in your browser.

Requirements

streamlit>=1.32.0
langchain-deepseek>=0.1.0
langchain-core>=0.2.0
langgraph>=0.1.0
pydantic>=2.0.0
python-dotenv>=1.0.0

🔄 Switching AI Providers

The LLM layer is fully abstracted through LangChain. Swapping providers requires only two changes.

OpenAI / GPT-4o

pip install langchain-openai
# app.py — replace init_llm()
from langchain_openai import ChatOpenAI

@st.cache_resource
def init_llm(model_name: str):
    return ChatOpenAI(model=model_name, temperature=0.2)

MODEL_OPTIONS = {
    "GPT-4o":       "gpt-4o",
    "GPT-4o Mini":  "gpt-4o-mini",
}
OPENAI_API_KEY=sk-...

Anthropic / Claude

pip install langchain-anthropic
from langchain_anthropic import ChatAnthropic

@st.cache_resource
def init_llm(model_name: str):
    return ChatAnthropic(model=model_name, temperature=0.2)

MODEL_OPTIONS = {
    "Claude 3.5 Sonnet": "claude-3-5-sonnet-20241022",
    "Claude 3 Haiku":    "claude-3-haiku-20240307",
}
ANTHROPIC_API_KEY=sk-ant-...

Google Gemini

pip install langchain-google-genai
from langchain_google_genai import ChatGoogleGenerativeAI

@st.cache_resource
def init_llm(model_name: str):
    return ChatGoogleGenerativeAI(model=model_name, temperature=0.2)

MODEL_OPTIONS = {
    "Gemini 1.5 Pro":   "gemini-1.5-pro",
    "Gemini 1.5 Flash": "gemini-1.5-flash",
}
GOOGLE_API_KEY=AIza...

Local / Ollama

pip install langchain-ollama
ollama pull codellama
from langchain_ollama import ChatOllama

@st.cache_resource
def init_llm(model_name: str):
    return ChatOllama(model=model_name, temperature=0.2)

MODEL_OPTIONS = {
    "CodeLlama 13B": "codellama:13b",
    "Llama 3.1 8B":  "llama3.1:8b",
}

Note: Local models may not reliably support with_structured_output(). If structured output fails, add a JSON extraction fallback in analyzer().

📁 Project Structure

code-notebook/
├── app.py              # Main Streamlit application
│   ├── LangGraph pipeline (file_loader → preprocessor → analyzer → summarizer)
│   ├── render_notebook()     — iframe-based Notebook renderer
│   ├── followup_llm()        — single-cell Q&A
│   ├── export_markdown()     — Markdown export builder
│   └── Streamlit UI layout
│
├── lang_config.py      # Language definitions and cell style palette
│   ├── LANG_MAP              — extension → (display name, comment style, hljs name)
│   ├── COMMENT_STRIP_TYPE    — extension → strip strategy
│   ├── _EXT_TO_STRIP         — flattened lookup dict
│   └── CELL_STYLES           — Tokyo Night color tokens per cell type
│
├── styles.css          # All visual styles (Tokyo Night design system)
│   ├── CSS custom properties (:root)
│   ├── Animation keyframes
│   ├── Badge, stream box, skeleton components
│   ├── Notebook cell (header, code, explanation)
│   ├── Search bar, collapse, toolbar buttons
│   └── Streamlit sidebar overrides
│
├── code_history/       # Auto-created; stores analysis JSON files
│   └── YYYYMMDD_HHMMSS_filename.json
│
├── .env                # API keys (not committed)
├── requirements.txt
└── README.md

🔬 How It Works

Upload File
    │
    ▼
┌─────────────┐     ┌──────────────┐     ┌─────────────────┐     ┌────────────┐
│ file_loader │────▶│ preprocessor │────▶│    analyzer     │────▶│ summarizer │
│             │     │              │     │                 │     │            │
│ Detect lang │     │ Strip        │     │ Smart chunk     │     │ 3-5 sent.  │
│ Decode file │     │ comments     │     │ LLM structured  │     │ overview   │
│ Count lines │     │ Extract      │     │ output per chunk│     │            │
│             │     │ keywords     │     │ Merge paired    │     │            │
└─────────────┘     └──────────────┘     │ tags            │     └────────────┘
                                         └─────────────────┘
                                                  │
                                                  ▼
                                         render_notebook()
                                         ┌─────────────────┐
                                         │ Build full HTML  │
                                         │ Inject via JS    │
                                         │ hljs highlight   │
                                         │ Line numbers     │
                                         │ Search / Fold /  │
                                         │ Copy / Resize    │
                                         └─────────────────┘

🗺️ Roadmap

Near-term

  • Collapse all — single button to fold/unfold all cells at once
  • Filter by type — pill buttons to show only function, class, etc.
  • Filter by difficulty — show only complex (⭐⭐⭐) cells for quick review
  • Jump-to-cell index — floating mini-map / table of contents on the right
  • History search — search across all saved history files by filename or language

Medium-term

  • Multi-file ZIP upload — analyze entire projects, generate per-file notebooks
  • Call graph visualization — mermaid.js diagram of function/class relationships
  • Test suggestion — auto-generate pytest / Jest stubs for function cells
  • GitHub URL input — paste a raw GitHub URL and analyze directly without downloading
  • PDF export — print-ready PDF via weasyprint or browser print API
  • Persistent user sessions — SQLite backend to persist history across restarts

Long-term

  • VS Code extension — right-click any selection → "Explain with Code Notebook"
  • Git diff mode — upload two versions of a file, explain only what changed
  • Collaborative annotation — shared read-only URL where multiple users can add comments
  • Learning path generator — given a multi-file project, recommend reading order by dependency depth
  • Incremental re-analysis — re-analyze only modified cells when a file is re-uploaded

🎨 Design System

The UI is built on the Tokyo Night color palette, consistent across all components:

Token Value Used for
--bg-base #1a1b26 Page background, explanation area
--bg-surface #1e2030 Cards, summary box, stream box
--code-bg #1e1e2e Code block background
--accent-blue #7aa2f7 import cells, info cards, search focus
--accent-green #9ece6a function cells, done badges
--accent-purple #bb9af7 class cells
--accent-orange #ff9e64 constant cells
--accent-yellow #e0af68 Summary box border, export stars
--accent-pink #f7768e decorator cells
--accent-teal #2ac3de config cells

🤝 Contributing

  1. Fork the repository
  2. Create a feature branch: git checkout -b feat/my-feature
  3. Commit your changes: git commit -m 'feat: add my feature'
  4. Push to the branch: git push origin feat/my-feature
  5. Open a Pull Request

Please keep PRs focused — one feature or fix per PR. CSS changes should preserve the Tokyo Night design tokens defined in :root.

📄 License

MIT © 2026 — see LICENSE for details.

Built with ❤️ using Streamlit · LangChain · LangGraph · highlight.js