BugSéance 👻 — A Local AI Investigator for the Ghosts Hiding in Your Logs

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

What I Built

Every developer has encountered a moment when an application suddenly stops behaving as expected.

The terminal fills with errors. A traceback points somewhere in the code. Something is undefined, a dependency is missing, or a service refuses to connect.

Sometimes the error is obvious. Sometimes figuring out what actually happened takes much longer than fixing it.

That's the problem I wanted to explore with BugSéance.

BugSéance is a local-first AI debugging investigator that reads application logs and turns them into structured debugging reports.

Instead of simply asking an AI chatbot, "What's wrong with my code?", you give BugSéance an actual log and let it investigate the evidence.

It produces a report containing:

• Summary: What appears to have happened.
• Root cause: The most likely explanation behind the issue.
• Observed facts: Evidence grounded in the supplied log.
• Likely explanations and unknowns: What can be inferred and what remains uncertain.
• Suggested fixes: Practical troubleshooting steps.
• Severity and confidence: An assessment of the issue and the model's estimated certainty.

It can also recognize when a log doesn't actually contain an error. A successful Uvicorn startup and an HTTP 200 OK response shouldn't turn into a fictional debugging problem.

I chose the Ghost in the Machine theme because debugging often feels like investigating something invisible. The application behaves unexpectedly, but the clues are scattered across its logs.

BugSéance gives that ghost a voice — and makes it show its evidence.

Demo

BugSéance is currently a local application. It does not have a deployed public instance.

The project uses local Ollama inference, so the intended experience is to run it on your own machine with the required model installed.

1. A Python ModuleNotFoundError investigation.
2. A normal Uvicorn startup log correctly recognized as non-failing.
3. A JavaScript TypeError investigation.
4. The structured report and Markdown export.

Screenshots:

Code

The complete source code is available on GitHub:

BugSéance — GitHub Repository

Repository: https://github.com/anmolchaudhary617-ux/BugSeance

The project has two main parts:

• frontend/ — React interface for log input, investigation reports, readiness status and Markdown export.
• backend/ — FastAPI service responsible for preparing analysis requests, communicating with Ollama, validating generated reports and handling errors.

How I Built It

BugSéance is built around Gemma 4 (gemma4:e2b) running locally through Ollama.

The idea was to make the open-weight model an essential part of the application, not just an optional chatbot added to an existing interface.

Architecture

Component	Technology
Frontend	React + Vite
Backend	Python + FastAPI
AI model	Gemma 4 (gemma4:e2b)
Inference runtime	Ollama
Request validation	Pydantic
Backend testing	Pytest

How an investigation works

The workflow is deliberately straightforward:

1. A developer pastes an error log or uploads a supported .txt or .log file.
2. The frontend sends the log and selected programming language to the FastAPI backend.
3. The backend prepares the input within the configured model context budget.
4. Ollama passes the request to the locally running Gemma model.
5. The generated response is validated against the expected report structure.
6. Evidence quotations are checked against the original supplied log.
7. The frontend displays the investigation and allows the report to be exported as Markdown.

Engineering decisions and challenges

The interesting part wasn't simply getting a model to explain an error. It was making its output more dependable.

1. Handling long logs

A model has a finite context window. Sending an entire large log without considering that limit can cause incomplete or failed responses.

I implemented bounded input preparation that accounts for the configured context size, output allowance and a safety margin. When necessary, it preserves the beginning and end of the log, along with selected diagnostic lines, and informs the user that content was omitted.

This uses approximate UTF-8 byte budgeting rather than an exact Gemma tokenizer.

2. Preventing invented evidence

A debugging assistant that confidently quotes something that never appeared in the log is not particularly useful.

BugSéance validates quoted evidence against the original user-supplied log. It also distinguishes observed facts from likely explanations and unknowns.

The objective is to make the model explain what it knows, rather than present every inference as a confirmed fact.

3. Handling unreliable model output

Structured AI responses aren't guaranteed to be valid every time.

I added response-envelope and report-schema validation, controlled Ollama error handling, and a bounded retry for malformed or incomplete model responses.

The retry is limited to two attempts, preventing an endless retry loop.

4. Frontend reliability

I also addressed issues such as stale reports appearing after the input changes, outdated asynchronous responses replacing newer results, and file-selection validation not triggering when the same invalid file is selected again.

The interface now distinguishes backend availability from Ollama/model readiness.

5. Keeping the application local-first

The final implementation removes the external Google Fonts dependency and keeps inference directed at the local Ollama service by default.

Suggested fixes remain suggestions. BugSéance does not execute commands or modify a developer's code automatically.

Testing

The latest automated release audit reported:

• Backend: 19 tests passed, 0 failed, 0 skipped.
• Frontend ESLint: passed.
• Frontend production build: passed.
• Git diff check: passed.

There is one existing Starlette/httpx test-client deprecation warning.

The final automated checks use mocked model responses. Although I manually tested earlier versions of BugSéance with Gemma and received sensible diagnoses, live Gemma inference was not repeated after the final trustworthiness changes. That remains an important validation step.

Why Does Open Innovation Matter?

For a debugging tool, application logs aren't always harmless text.

They can contain internal service names, file paths, database details, API responses and other information developers may not want to send to a third-party service.

Using an open-weight model through local inference gives BugSéance a different architecture.

Instead of depending on a hosted proprietary AI API for every investigation, the application communicates with an Ollama instance running on the developer's machine.

This matters in a few practical ways:

• Privacy and control: Logs can remain on the local machine when using the default local configuration.
• Flexibility: The model and inference configuration can be changed without redesigning the entire application.
• Accessibility: Developers with compatible hardware can experiment without needing a paid hosted inference API.
• Independence: The core investigation workflow isn't tied to a single proprietary AI provider.

There is an important distinction: the model must first be installed or downloaded, and changing the Ollama endpoint to a remote server changes the privacy assumptions. Local inference is the intended default, not an unconditional guarantee that every setup is offline.

Open innovation made it possible to build a debugging assistant around developer control instead of treating it as an afterthought.

The Spirit of It

The name BugSéance started with a simple idea: debugging sometimes feels like holding a séance.

You have traces of something that happened, but you weren't there when it happened. You ask questions, examine the evidence, and try to reconstruct the event.

One of the most useful moments during development was testing the application with a perfectly normal Uvicorn startup log.

Instead of inventing a crash, BugSéance correctly recognized that the server had started and the request had returned 200 OK.

That matters to me because a debugging tool shouldn't manufacture a haunting just to justify its existence.

The machine may be haunted. But every ghost should have to show its evidence. 👻

Prize Categories

I'm entering the following categories based on the technologies used in the project:

• Best Use of Gemma — Gemma 4 is the core model used for local log investigation through Ollama.
• Best Use of GitHub Copilot — GitHub Copilot's coding agent was used during project inspection, implementation and reliability improvements.