DEV Community: Vaibhav Bharathula

How I Built RepoSéance: A Local-First AI Ghost Hunter That Resurrects Abandoned Codebases

Vaibhav Bharathula — Sat, 31 Oct 2026 16:27:33 +0000

This is a submission for the Hacktoberfest Open-Source AI Challenge Week 4: Ghost in the Machine

What I Built

Every developer knows the eerie feeling: you stumble across a dusty GitHub repository from 4 years ago that solved the exact esoteric problem or algorithmic challenge you are wrestling with today.

You excitedly clone it, only to find:

The sole maintainer vanished in 2022.
The README.md is a 3-line stub that says "WIP, documentation coming soon."
Half the architecture relies on undocumented assumptions and buried // TODO: fix race condition in worker loop.
Key dependencies are deprecated or completely broken.
You have no idea what the entry point is, whether it ever worked, or if it's worth your time to resurrect.

Sending a proprietary or private codebase to cloud AI APIs poses massive confidentiality risks and burns expensive tokens. And what happens when you need to inspect code on an offline plane or in a high-security environment?

I built RepoSéance to bring these ghost codebases back to life.

RepoSéance is a local-first, privacy-respecting software archaeology companion. You provide a local directory path or upload a ZIP archive of any neglected project, and RepoSéance conducts a digital séance:

Deterministic Repository Archaeology: Safely maps directory structures, scans dependencies, inspects local Git commit histories, and catalogs buried TODO/FIXME markers without executing a single line of untrusted code.
Local Code Indexing & Bounded Evidence Retrieval: Chunks source code, extracts semantic tokens, and builds an offline vector index using local embedding models (nomic-embed-text / bge-small-en).
Structured Project Autopsy: Uses a locally running open-weight model (Qwen2.5-Coder / Qwen2.5-3B / Gemma 2-2B via Ollama) to reconstruct the project's true purpose, identify architecture flows, highlight entry points, and distinguish verified facts from AI hypotheses.
Interactive Ghost Chat: A conversational assistant with a subtle haunted-archive persona that answers technical queries about the codebase, strictly backed by clickable citations referencing exact file paths and line ranges.
Actionable Revival Roadmap: Automatically compiles an interactive triage checklist (bug fixes, dependency modernizations, documentation patches, missing tests) and exports a complete Markdown autopsy dossier.

Local Repository / ZIP ──> Safe Scanner & Secret Redactor ──> Deterministic AST & Git Parser
                                                                        │
                                ┌───────────────────────────────────────┴───────────────────────────────────────┐
                                ▼                                                                               ▼
             Local Embeddings (Nomic / BGE)                                                     Git History & TODO Extractor
                                │                                                                               │
                                ▼                                                                               │
                         Local Vector Index                                                                     │
                                │                                                                               │
                                └───────────────────────────────┬───────────────────────────────────────────────┘
                                                                ▼
                                                Evidence Retrieval & Chunk Citations
                                                                │
                                ┌───────────────────────────────┴───────────────────────────────┐
                                ▼                                                               ▼
                 Ollama Runtime (Qwen2.5 / Gemma 2)                              Offline Deterministic Autopsy Fallback
                                │                                                               │
                                └───────────────────────────────┬───────────────────────────────┘
                                                                ▼
                                            Digital Séance Dashboard & Ghost Chat
                                            - Project Autopsy & Architecture
                                            - Evidence-Cited Q&A
                                            - Prioritized Revival Roadmap
                                            - Exportable Markdown Dossier

Demo

RepoSéance embraces a futuristic, haunted-terminal aesthetic: sleek dark charcoal backgrounds, spectral violet (#9d4edd) and muted cyan accents, glassmorphic cards, and crisp monospace typography.

The application is organized into 5 focused modules:

🕯️ The Séance Chamber (Landing & Import): Instant local folder selection or ZIP dropzone, live model availability heartbeat, and zero-cloud privacy verification.
📜 Project Autopsy: Comprehensive architectural breakdown, primary entry points, dependency health check, and Git activity timelines.
👻 Ghost Chat: Technical Q&A with collapsible Evidence Cards showing exact source file paths and line number snippets (src/core/router.py:L45-L78).
🗺️ Revival Roadmap: Prioritized triage tasks (Investigate First, Modernization, Missing Tests, Documentation) with interactive state toggling (Pending, In Progress, Resolved).
📄 Exportable Dossier: One-click Markdown export summarizing the full autopsy and action plan for team handoffs or GitHub issues.

1. Summoning the Codebase

Select a local repository or drag in a ZIP archive. RepoSéance validates the path, respects .gitignore, redacts detected credentials, and extracts Git commit timelines in seconds:

2. The Project Autopsy & Architectural Map

The local AI reconstructs high-level module relationships, flags undocumented entry points, and catalogs uncompleted TODOs:

3. Ghost Chat with Verifiable Evidence Cards

Ask technical questions about esoteric functions or forgotten data pipelines. The Ghost answers with technical rigor and explicit file citations:

4. Interactive Revival Roadmap

Filter by priority and track tasks as you bring the project back to life:

Running It Locally

RepoSéance requires zero external API keys and runs completely on standard laptop hardware:

# 1. Clone the repository
git clone https://github.com/Vaibhav-1819/RepoS-ance.git
cd RepoS-ance

# 2. Set up the Python backend
cd backend
python -m venv venv
# Windows:
.\venv\Scripts\activate
# Linux/macOS:
source venv/bin/activate
pip install -r requirements.txt

# 3. (Optional) Start Ollama for local LLM inference
ollama run qwen2.5-coder:7b
# Or smaller models for lightweight laptops:
# ollama run qwen2.5:3b or ollama run gemma2:2b

# 4. Start the backend server
uvicorn main:app --reload --port 8000

# 5. In a new terminal, launch the frontend
cd ../frontend
npm install
npm run dev

Note: If Ollama is not running, RepoSéance automatically activates its built-in deterministic heuristic engine, providing complete structural autopsies, Git analyses, and TODO inventories without failing.

Code

Vaibhav-1819 / RepoS-ance

The complete codebase is 100% open-source under the MIT license:

backend/scanner/: Deterministic repository walker, directory tree generator, secret masker, and Git history analyzer.
backend/indexer/: Syntax-aware code chunker, local embedding orchestrator, and vector retrieval storage.
backend/ai/: Ollama runtime client, ghost prompt contracts, structured autopsy schema, and deterministic heuristic fallback.
backend/main.py: FastAPI REST API delivering health checks, autopsy generation, evidence-backed chat, and report downloads.
frontend/: React + TypeScript dashboard with spectral visual theme, tabbed autopsy views, interactive roadmap cards, and Markdown export.

How I Built It

1. The Open-Source AI Architecture

Processing unfamiliar codebases with local open-weight models presents two major hurdles: context window limits and hallucination risk.

Feeding 50,000 lines of raw code into a local 3B or 7B model causes memory thrashing, high latency, and severe hallucinations. RepoSéance overcomes this with a Bounded Evidence Pipeline:

Deterministic Bouncer: Before LLM inference, the scanner strips out binary assets, build artifacts (node_modules, venv, target, dist), and redacted environment files.
Structural Chunking: Files are segmented into functional units (classes, functions, top-level definitions, README sections) preserving exact line numbers (start_line, end_line).
Evidence-Limited Prompting: Instead of entire files, the local model receives a compact 800-token evidence bundle consisting of the README abstract, primary entry points, key dependencies, and high-similarity code snippets.
Fact vs. Hypothesis Separation: The system prompt explicitly enforces a strict boundary:
- Verified Fact: Direct quote or observed structural attribute (e.g., Flask 1.1.2 defined in requirements.txt:L4).
- Inference: Logical deduction based on code flow.
- Hypothesis: Speculation that requires developer testing.

2. Safety and Sandboxing

Because RepoSéance is built to inspect untrusted, abandoned repositories, security is a non-negotiable prerequisite:

Never Executes Code: No build commands, package managers (npm install, pip install), or repository scripts are ever invoked.
Path Traversal Protection: Archive extraction strictly validates target paths to prevent directory traversal attacks (../../evil.sh).
Prompt Injection Defense: Source code and documentation excerpts are treated strictly as untrusted data containers, separated from system instructions with robust delimiters.

Why Does Open Innovation Matter?

Open-source software powers the modern digital economy, but thousands of promising repositories are abandoned each year due to maintainer burnout, corporate shifts, or life changes.

Digital Preservation & Software Archaeology: When code is left behind, the institutional knowledge of why it was built that way disappears. RepoSéance ensures that any developer can unearth, comprehend, and revive forgotten software independently.
Total Privacy for Proprietary Assets: Companies frequently possess internal legacy repositories that have had no active maintainer for years. They cannot upload confidential IP or internal infrastructure code to cloud AI services. Local AI models running on localhost make legacy code triage 100% compliant and private.
Resilience from Corporate API Churn: Cloud AI models are frequently deprecated, price-hiked, or modified behind closed doors. With local open-weight weights (Qwen2.5, Gemma 2), your software archaeology workbench will continue working 10 years from now—even on an isolated machine with no internet connection.

My First "Resurrection" Test

To put RepoSéance to the test, I summoned a 3-year-old abandoned Python CLI audio transcriber repository that had been archived on GitHub with the commit message "pausing for now".

What RepoSéance unearthed in under 20 seconds:

Identified Entry Point: Spotted cli.py as the true driver, despite the README claiming main.py was the execution point.
Flagged Deprecated Dependency: Detected an unpinned pydantic<1.9 requirement causing silent type conversion crashes on modern Python 3.11+.
Uncovered Hidden WIP: Found an incomplete multi-threaded chunking routine in transcribe/stream.py:L89 marked # FIXME: buffer underrun when stream terminates abruptly.
Generated Revival Checklist: Provided a clean, 4-step modernization plan that allowed me to patch the dependencies, fix the buffer condition, and run the transcriber successfully.

Over to You: Let's Discuss in the Comments!

I would love to hear your thoughts and experiences:

What is the most promising abandoned open-source repository you've ever discovered that was simply too cryptic to revive?
Have you explored running local code-specific models (like Qwen2.5-Coder or DeepSeek-Coder) for offline developer tooling?
What features would help you most when inspecting unfamiliar codebases: AST call-graph visualizers, automatic test generator suggestions, or Dockerfile generators?

If you find this project valuable, please give it a star on GitHub and share your thoughts below! I'll be in the comments answering questions and discussing software archaeology.

Prize Categories

Primary Track: Hacktoberfest Open-Source AI Challenge Week 4 — Ghost in the Machine
Open-Source Innovation Track: Advancing local-first, privacy-preserving software archaeology with open-weight models and zero data leakage.

How I Built SlothFlow: A Local-First AI File Organizer That Cleans Your Mess While You Relax

Vaibhav Bharathula — Sun, 25 Oct 2026 16:26:41 +0000

This is a submission for the Hacktoberfest Open-Source AI Challenge Week 3: Slow and Steady

What I Built

If you’ve ever opened your Downloads or Desktop folder and winced at the mountain of unorganized documents staring back at you—doc1.pdf, scan_003.pdf, notes_final.txt, download_482.md, and cryptic invoice numbers—you know the exact pain of digital chaos.

Manually opening each document, skimming its contents, thinking of a descriptive filename, and dragging it into the right subfolder is tedious, repetitive, and draining work.

Most cloud-based file organizers either require paying recurring monthly API subscriptions or, even worse, uploading your private tax filings, apartment leases, health records, and bank statements to third-party cloud servers. That is an unacceptable privacy hazard.

I built SlothFlow to solve this once and for all.

SlothFlow is a local-first web application powered by open-weight AI models (Qwen2.5-1.5B, Gemma 2-2B, or Llama 3.2-1B) running on localhost via Ollama. It inspects documents on your machine, determines their categorization, generates human-readable filenames, and safely organizes them into clean category folders—all while ensuring zero document bytes ever leave your laptop.

Disorganized Folder ──> Safe Text Extractor (PyMuPDF) ──> Bounded Content Snippet
                                                                    │
                            ┌───────────────────────────────────────┴───────────────────────────────────────┐
                            ▼                                                                               ▼
             Local Ollama (Qwen 2.5 / Gemma 2)                                              Offline Heuristic Engine
             Strict Structured JSON Response                                                 Pattern & Keyword Matcher
                            │                                                                               │
                            └───────────────────────────────────────┬───────────────────────────────────────┘
                                                                    ▼
                                                    Interactive Organization Plan
                                                    - Inline Rename & Approval
                                                    - Collision Avoidance Guard
                                                                    │
                                                                    ▼
                                                    Safe Atomic Move & SQLite Audit Log
                                                    (Instant 1-Click Safe Undo)

The "Slow and Steady" Philosophy & Lazy Mode

The challenge theme for Week 3 is "Slow and Steady"—and who embodies that better than a sloth?

🦥 Lazy Mode (1-Click Auto-Pilot): Select a folder and click "Organize My Files". SlothFlow automatically extracts text, classifies categories, resolves filename collisions, organizes your folder, and hands you a tidy summary report while you kick back and relax.
🔍 Step-by-Step Preview Mode: For detail-oriented builders, you can review the proposed moves in an interactive table, rename files inline, adjust target categories, and toggle granular approvals before anything touches your filesystem.
🛡️ Safe Undo & Zero Overwrites: We guarantee zero overwrites and zero file deletions. Every single move is logged in an on-device SQLite audit trail with an instant Safe Undo button that verifies paths for conflicts before restoring.

Demo

SlothFlow features a minimal dashboard styled in warm earth tones, glassmorphism cards, and a peaceful sloth identity:

1. Large Folder Drop & Pre-Packaged Demo Fixtures

Choose any disorganized folder on your machine, or click "Load Demo Folder" to test with the 18 realistic sample documents included directly in the repository (leases, balance sheets, discrete math homework, sprint backlogs, and cloud invoices):

📂 D:\Projects\SlothFlow\demo_files
├── doc1.pdf               --> [Finance]    Quarterly_Financial_Performance_Q3_Balance_Sheet.pdf
├── notes_final.txt        --> [Education]  Java_Collections_Framework_and_Concurrency_Interview_Notes.txt
├── download_482.md        --> [Projects]   React_Architecture_and_State_Management_Implementation_Guide.md
├── scan_003.pdf           --> [Personal]   Residential_Tenancy_Agreement_and_Apartment_Lease_Contract.pdf
├── project_stuff.txt      --> [Projects]   SlothFlow_Sprint_Backlog_and_Product_Roadmap.txt
└── inv_9841.pdf           --> [Finance]    Cloud_Infrastructure_Monthly_Hosting_Invoice.pdf

2. Interactive Organization Plan Preview

The local open-weight model evaluates each document and returns a structured organization plan:

Original Filename: With icon badges for PDF, Markdown, JSON, and Text documents.
Suggested Filename: Editable inline with live pencil action.
Category Badge: Work (Blue), Education (Purple), Finance (Emerald), Personal (Rose), Projects (Amber), and Miscellaneous (Slate).
Target Destination: Shows planned subfolder (/Finance/, /Education/).
Confidence & Reasoning: Real-time progress bar displaying model confidence and explanation.

3. Safe Rollback & Audit Log

If you ever change your mind, open the Audit Log or click "Undo Organization" on the completion screen. SlothFlow cross-checks file existence, verifies destination availability, and safely restores files back to their exact original names and paths.

Running It Yourself

You don't need expensive GPU clusters. SlothFlow runs smoothly on standard developer laptops:

# 1. Clone the repository
git clone https://github.com/Vaibhav-1819/slothflow.git
cd slothflow

# 2. Set up and start the FastAPI Backend
cd backend
pip install -r requirements.txt
python run.py

# 3. Set up and launch the React Frontend (in a second terminal)
cd ../frontend
npm install
npm run dev

# 4. (Recommended) Pull your favorite local open-weight model
ollama run qwen2.5:1.5b

Tip: If Ollama isn't installed yet, SlothFlow's built-in **Heuristic Fallback Engine* automatically engages so you can test the entire scanning, plan generation, and safe undo workflow right out of the box!*

Code

Vaibhav-1819 / slothflow

🦥 SlothFlow — Your Local AI File Organizer

"Stop organizing. Start relaxing."
Built for the Hacktoberfest Open-Source AI Challenge — Week 3: Slow and Steady

📖 Overview

People accumulate hundreds of disorganized files: messy PDFs (scan_003.pdf), ambiguous meeting notes (notes_final.txt), downloaded specs (download_482.md), and raw receipts. Manually opening, reading, renaming, and filing these documents into neat folders is tedious and draining.

Cloud-based AI organizers require uploading confidential documents, invoices, tax forms, and medical records to external corporate servers or paying monthly API fees.

SlothFlow is a local-first, privacy-respecting file organizer powered by open-weight AI models (Qwen 2.5, Gemma 2, Llama 3.2 via Ollama). It reads documents on your laptop CPU/GPU, determines their classification, suggests clean descriptive filenames, and organizes them into curated folders—all while ensuring zero document bytes ever leave your machine.

Disorganized Folder ──> Safe Text Extractor (PyMuPDF) ──> Bounded Content Snippet
                                                                    │

…

View on GitHub

The complete project is open-source under the MIT license:

backend/app/classifier.py: Local Ollama client prompting open-weight models for structured JSON output (format: "json"), status caching, and heuristic fallback.
backend/app/extractors.py: Local document text extractor using PyMuPDF (pymupdf) for PDFs and multi-encoding decoders for text/markdown.
backend/app/security.py: Path boundary validation (is_path_within_base), filename sanitization, and collision-free auto-incrementing.
backend/app/organizer.py: Plan generator and atomic filesystem executor.
backend/app/undo.py: Safe rollback engine verifying target availability before restoring.
backend/app/db.py: SQLite audit logging and session persistence.
frontend/src/App.tsx: Main dashboard orchestrating state, inline editing, Lazy Mode, and undo modals.

How I Built It

The Open-Source AI Architecture

To make local file organization responsive and reliable on everyday hardware, I implemented four core architectural principles:

Untrusted Content Isolation: Document contents are untrusted data. SlothFlow treats extracted document text strictly as passive data inside the prompt. We isolate the snippet in clear boundary tags so prompt injection instructions embedded inside a document are never executed.
Bounded In-Memory Extraction: Passing a 50-page PDF to a local 1.5B LLM will throttle token speed and inflate memory usage. SlothFlow extracts text via PyMuPDF and packages a clean, bounded 1,800-character snippet capturing the title, headers, and opening paragraphs—achieving sub-second classification latency per document.
Deterministic Collision Prevention: AI models can suggest identical filenames for related documents (e.g. two AWS invoices). Our filesystem layer checks the target directory and active plan claims, auto-incrementing filenames (_1, _2) before applying changes so no file is ever overwritten.
Sandboxed Directory Boundaries: All filesystem reads and moves enforce validate_and_resolve_folder() and is_path_within_base(). It is mathematically impossible for the application to touch or escape into files outside the user's selected directory.

Why Does Open Innovation Matter?

Uncompromised Document Privacy: Personal files contain tax IDs, salaries, medical test results, and confidential code. Relying on centralized cloud AI requires handing over your private data. With open-weight models (Qwen2.5, Gemma 2, Llama 3.2), your private documents stay completely on your machine.
Zero API Cost & Unlimited Usage: Organizing 2,000 messy archive documents using commercial cloud APIs would cost dollars per batch. With open-weight AI on localhost, you can organize thousands of documents for free without hitting rate limits or credit cards.
Resilience & Offline Independence: SlothFlow functions in the woods, on a plane, or during network blackouts. Once the model is downloaded, you own your productivity pipeline.

Real-World Test Run

To test SlothFlow against genuine edge cases, we built an included dataset of 18 messy files:

Original File	Content Type	SlothFlow Proposed Name	Destination	Result
`doc1.pdf`	Balance sheet	`Quarterly_Financial_Performance_Q3_Balance_Sheet.pdf`	`/Finance/`	✅ Moved
`scan_003.pdf`	Apartment lease	`Residential_Tenancy_Agreement_Apartment_Lease.pdf`	`/Personal/`	✅ Moved
`notes_final.txt`	Java notes	`Java_Collections_Framework_Concurrency_Notes.txt`	`/Education/`	✅ Moved
`project_stuff.txt`	Sprint backlog	`SlothFlow_Sprint_Backlog_Product_Roadmap.txt`	`/Projects/`	✅ Moved
`empty_scratch.txt`	Empty 0-byte file	`empty_scratch.txt`	`/Miscellaneous/`	⏭️ Skipped gracefully

Safe Undo Test:

After applying all 18 moves, clicking "Undo Organization" cleanly checked directory conflicts, moved all 18 files back into the root directory, deleted the now-empty category folders, and updated the SQLite audit trail to undone.

Over to You: Let's Discuss in the Comments!

How messy is your Downloads folder right now? How many hundreds (or thousands) of files are sitting there?
What open-weight model have you found best for structured JSON output on CPU (Qwen 2.5, Gemma 2, or Llama 3.2)?
Which features would you love next: automatic deduplication, optical character recognition (OCR) for scanned receipts, or a CLI daemon mode?

Star the repo on GitHub and let me know your thoughts in the comments below! 🦥

Prize Categories

Primary Track: Hacktoberfest Open-Source AI Challenge Week 3 — Slow and Steady
Open-Source Innovation Track: Local-first, privacy-guaranteed document processing and intelligent file reorganization using open-weight AI models.

How I Built TraceLite AI: A Local-First Debugging Assistant That Saves You From Log Hell

Vaibhav Bharathula — Sat, 17 Oct 2026 16:21:47 +0000

This is a submission for the Hacktoberfest Open-Source AI Challenge Week 2: Side Hustle

What I Built

If you've ever stared at a 3,000-line terminal wall of raw logs after a midnight deployment crash, you know the exact pain I’m talking about.

You scroll frantically, trying to figure out which line is the actual root cause and which 200 lines are just cascading warning noise. Most small teams and indie devs I know don't have $300/month to drop on enterprise observability suites like Datadog or Dynatrace. And even if you do, sending proprietary server logs containing user IDs and database queries to external cloud AI APIs is a massive privacy risk.

I built TraceLite AI to solve this.

It is a lightweight, local-first debugging companion. You paste in an unreadable stack trace or upload a raw .log file, and TraceLite:

Redacts secrets instantly (stripping out auth headers, OpenAI keys, and database passwords before anything touches memory).
Deterministically clusters the noise (grouping repeated error templates and isolating the actual failure point).
Runs a local open-weight AI model (Qwen2.5-0.5B) via Ollama right on your laptop CPU to explain why it crashed and generate an actionable fix checklist.
Exports a clean Markdown report that you can drop directly into a GitHub issue or pull request.

Raw Logs ──> Secret Masker ──> Deterministic Parser ──> Bounded Evidence Package
                                                                │
                            ┌───────────────────────────────────┴───────────────────────────────────┐
                            ▼                                                                       ▼
             Ollama Runtime (Qwen2.5-0.5B)                                          Offline Heuristic Fallback
                            │                                                                       │
                            └───────────────────────────────────┬───────────────────────────────────┘
                                                                ▼
                                                    Evidence-First Investigation
                                                    & Markdown Report Export

Who would pay for this? (The Side Hustle Thesis)

I designed TraceLite around an open-core model:

100% Free & Open Source Core: The local CLI and standalone Streamlit web app will always remain free. Solo builders and CS students shouldn't have to pay to debug their side projects.
Hosted Team Convenience Layer ($12–$19/month per team): Small agencies and startups don't want to pass raw logs around Slack. The paid tier will offer:
- A shared team investigation inbox with privacy-scrubbed crash histories.
- One-click GitHub & Linear integrations that convert a triage report into an assigned bug ticket.
- A GitHub Actions CI/CD bot that automatically runs TraceLite on failed test logs and posts a human explanation on the pull request.

Demo

TraceLite AI features a modern, responsive web application styled with Space Grotesk typography, glassmorphic card elements, a floating top Navbar, and a persistent Footer with 5 dedicated sections:

🔍 Log Investigator: Live triage console, one-click fixtures, stack trace isolation, and Markdown exporter.
🚀 Architecture: Interactive breakdown of the bounded evidence packaging pipeline.
📖 Docs & CLI: Setup instructions, demo_app.py walkthrough, and automated testing guide.
💼 Side Hustle & Pricing: Comparison between the free Community Core and the paid Team Convenience Layer ($15/seat/mo).
🛡️ Privacy Engine: Deep-dive into automated regex masking of API keys, tokens, and database passwords.

Here is how the end-to-end investigation workflow looks in practice:

1. Ingesting Logs & Isolating Errors

Paste raw logs, upload a file, or click a sample fixture. TraceLite instantly runs secret masking, isolates the primary error in a clear red banner, and prepares the triage report:

2. Deterministic Metrics & Stack Trace Extraction

The engine parses multi-language stack traces (Python, Java JVM, Node.js, Go), computes line-by-line metrics, and reveals surrounding context lines:

3. AI Investigation & Diagnostic Checklist

The local open-weight model (Qwen2.5-0.5B) provides plain-language explanations, identifies plausible root causes, and generates an ordered diagnostic checklist:

Running It Yourself

You don't need a GPU. It runs on any standard laptop:

# 1. Clone the repo
git clone https://github.com/Vaibhav-1819/tracelite_ai.git
cd tracelite_ai

# 2. Install requirements
pip install -r requirements.txt

# 3. (Optional) Run Ollama if you want the local LLM enabled
ollama run qwen2.5:0.5b

# 4. Fire up the dashboard
streamlit run app.py

Tip: If you don't have Ollama installed, don't worry! TraceLite automatically activates its built-in heuristic engine so you get immediate diagnostic reports without installing anything extra.

Code

Vaibhav-1819 / tracelite_ai

🔍 TraceLite AI

Lightweight, local-first debugging assistant that converts raw application logs and stack traces into structured, actionable investigation reports.

💡 Overview

When applications crash, developers are often confronted with massive walls of logs: repeated exceptions, noise, obscure JVM traces, or unhandled Python errors. Traditional observability suites are complex, expensive, and require transmitting proprietary server logs to third-party clouds.

TraceLite AI solves this with a zero-cost, local-first architecture:

Deterministic Parsing & Extraction: Fast Python regex engine parses multi-language stack traces (Python, Java, Node.js, Go), clusters recurring error signatures, normalizes dynamic variables, and builds event timelines.
Automated Secret & Credential Redaction: API keys (OpenAI, AWS, GitHub), bearer tokens, database passwords, and JWTs are automatically stripped before analysis or export.
Open-Weight AI Investigation: An ultra-lightweight open-weight LLM (Qwen2.5-0.5B-Instruct via Ollama) provides plain-language explanations, root-cause hypotheses, and ordered debugging steps.
Graceful Fallback: Operates 100% offline with deterministic heuristics if Ollama is…

View on GitHub

The entire codebase is open-source under the MIT license:

tracelite/parser.py: The deterministic regex engine that parses Python, Java (JVM stack traces with Caused by:), JavaScript/Node.js, and Go panics.
tracelite/masker.py: The privacy filter catching AWS keys, Bearer tokens, DB credentials, and API secrets.
tracelite/ai_client.py: Ollama integration with bounded evidence packaging and deterministic offline fallback.
app.py: The Streamlit web interface styled with Space Grotesk typography and custom glassmorphism.
tests/: 11 unit tests covering all parsers and failure edge cases (pytest passes 100%).

How I Built It

The Open-Source AI Architecture

I deliberately avoided heavyweight models. Instead, I paired a small open-weight language model (Qwen2.5-0.5B-Instruct) with a fast Python preprocessing pipeline:

The Context Problem: Small 0.5B models get confused if you throw 5,000 lines of raw logs at them. Their context windows choke, latency spikes, and they start hallucinating.
The Bounded Evidence Solution: I built a deterministic parser that acts as a bouncer. It strips out timestamps, masks sensitive tokens, clusters recurring messages (e.g. converting POST /checkout 500 repeated 40 times into a single line with count=40), and sends only a clean, 300-token evidence summary to the model.
Strict JSON Schema Guardrails: The prompt forces the model to respond strictly in structured JSON, returning an explanation, plausible root causes, ordered diagnostic steps, and an uncertainty statement.
Graceful Fallback: If Ollama is sleeping or not installed, TraceLite doesn't crash. It seamlessly routes through a deterministic heuristic rule engine that diagnoses common errors (ZeroDivisionError, NullPointerException, HTTP 429, HTTP 500) with honest attribution.

Why Does Open Innovation Matter?

Building this project made one thing crystal clear: some problems should never be handed to closed cloud APIs.

Real Data Privacy: Debugging server crashes means touching sensitive data: internal hostnames, database connection strings, and user payloads. Feeding raw production logs into a closed third-party cloud API is an unacceptable compliance risk for most developers. Open-weight models running on localhost keep your data where it belongs.
Zero Marginal Cost: If I had to pay $0.02 per OpenAI API call every time I tested a log parser against large logs, building this side hustle would have cost me money before getting my first user. With open-weight AI, I ran thousands of test parses for exactly $0.
Resilience & Independence: Closed APIs can change pricing, deprecate model versions, or suffer outages during your own production downtime. With Qwen2.5 and Ollama, my debugging tool works on a plane at 30,000 feet with zero Wi-Fi.

My First User

To test TraceLite in the real world, I asked an indie developer friend to test-drive it on a tricky issue in their FastAPI application. Their container logs were drowning in sporadic 500 errors.

What TraceLite did in under 3 seconds:

Stripped their PostgreSQL password from the raw connection string before displaying anything.
Collapsed 42 repetitive connection failure lines into a single cluster.
Pinpointed that their async connection pool was running out of open slots during checkout surges.

Their reaction:

"Usually when a server goes down, I'm grepping terminal windows with tail -n 100 and piecing together the timeline in my head. TraceLite pulled the exact culprit straight out of the noise and gave me a checklist I could follow right away. The fact that it runs locally without uploading my database errors to the cloud is a game changer."

Over to You: Let's Discuss in the Comments!

I'd love to hear your thoughts and war stories:

What is the nastiest, most cryptic stack trace you’ve had to troubleshoot recently?
Have you experimented with small open-weight models (like Qwen2.5 0.5B or Llama 3.2 1B) for local development tools?
What integration would you find most useful: a VS Code extension, a GitHub Actions PR bot, or a CLI pipe (my_cmd 2>&1 | tracelite)?

If you found this project helpful or interesting, feel free to share it with your team, coworkers, or developer community, and star the repo on GitHub! Drop any questions or feedback below—I'll be hanging out in the comments to reply to every single one.

Prize Categories

Primary Track: Hacktoberfest Open-Source AI Challenge Week 2 — Side Hustle
Open-Source Innovation Track: Demonstrating practical, local-first inference using Qwen2.5-0.5B-Instruct on everyday hardware with zero API fees.