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

Every dead repo ends mid-sentence. I built a Gemma that's only allowed to quote it.

"Every dead repo ends mid-sentence. Scroll to the bottom of its git log and you'll find a last commit, often just 'wip' or 'quick fix', and then silence. I wanted to ask what the sentence was going to be.

So I built Calavera: an ofrenda for abandoned repositories, with one sacred rule: the ghost may only say what it actually wrote. Every line is cited to a commit SHA or issue number. When the record is silent, so is the ghost."

🕯️ What I Built

Every week across GitHub, thousands of repositories fall silent. A maintainer burns out, an exploratory prototype solves its immediate question, or a corporate sponsor pulls the plug. We often treat dead code as digital landfill—deprecate, archive, delete.

Calavera treats abandoned repositories as ancestral records. Inspired by the traditions of Día de los Muertos and the lighting of ceremonial lamps for departed forebears, Calavera is an open-source, local-first digital ofrenda and archival séance engine with four core components:

1. The 14 Ancestral Lamps: A purely deterministic ceremonial timeline displaying the repository's final 14 commits as flickering flame lamps. Hovering or clicking reveals verbatim commit messages, author signatures, timestamps, and files modified—no LLM invention allowed.
2. The Grounded Tombstone Card: A shareable artifact calculating cold, verifiable facts (lifespan, total commit count, stars, forks, and the exact verbatim last words written before silence) alongside a 2-line calavera mock-epitaph generated by local Gemma. A deterministic validator cross-references the verse against the factual record, discarding any verse that introduces an ungrounded number, author name, or date. It exports directly to a PNG memorial card in one click.
3. The Séance Engine with Deterministic Verification: An interactive terminal where developers can ask what the repository was trying to accomplish, why architectural decisions were made, or why it ceased development. Gemma responds through native structured function-calling (cite(source_type, identifier, claim, quote)).
4. "The Log Is Silent" Hard Guarantee: A deterministic verification layer intercepts every generated citation. If an LLM cites a nonexistent SHA, references an issue that never existed, or hallucinates features absent from the codebase, the claim is dropped. If all claims are discarded, the ghost outputs: "The log is silent."

🧬 My Personal Tie: The Vanished Multi-Agent Graveyard

This project comes from an acute personal frustration. Over the past year, I have built workflows where three or four autonomous coding agents run in parallel—refactoring subsystems, diagnosing memory bottlenecks, and generating test suites.

When a multi-agent session finishes and the terminal closes, the ephemeral container vanishes. Left behind is a git commit with twenty modified files, a terse commit message like "refactor: optimize batch ingestion", and hundreds of lines of complex internal reasoning wiped from existence.

Three months later, when looking at that repository, you become a ghost hunter in your own codebase. You wonder: Why was this buffer allocated this way? Was there a concurrency edge case that prompted this lock?

To test Calavera on modern ghosts, I seeded our demo with three distinct graveyards:

1. request/request: The monolithic HTTP client that once powered the entire Node.js ecosystem, downloaded billions of times, before officially deprecating in 2020.
2. charliesome/charlock_holmes: The beloved character-encoding detection library whose maintainer Charlie Somerville tragically passed away in 2023, leaving behind heartbreakingly human last commits.
3. farhanmallik05/ephemeral-agent-loop: My own multi-agent experimental repository, whose autonomous reasoning threads were retrieved and grounded straight from SQLite index traces.

Figure: Shareable memorial card generated for request/request: deterministic facts + local Gemma calavera verse validated against the historical ledger.

🛠️ How I Built It

Calavera is designed with a zero-trust architecture toward model generation. Models are creative; historical archives must be immutable.

flowchart TD
    A["Abandoned Git Repository / SQLite"] --> B["Deterministic Ingestion Engine"]
    B --> C["14 Ancestral Lamps (Pure Git Log)"]
    B --> D["Factual Ledger (Dates, SHAs, Last Words)"]

    E["User Séance Query"] --> F["Context Index (Commits, Issues, TODOs)"]
    F --> G["Gemma 4 / Local LLM (Structured cite() Calls)"]

    G --> H{"Deterministic Citation Verifier"}
    H -->|Valid SHA & Grounded Topic| I["Rendered Ghost Response with Hyperlinked Citations"]
    H -->|Hallucinated SHA or Trap Query| J["Redacted / Dropped Claim"]

    J --> K{"Any Grounded Claims Left?"}
    K -->|Yes| I
    K -->|No| L["'The log is silent.'"]

The Ingestion Layer (calavera/ingest.py)

Calavera mines standard Git repositories or pre-indexed GitHub archive dumps into a lightweight SQLite ledger. It indexes:

• Commit SHAs, author names, ISO timestamps, and commit messages.
• Issue titles, bodies, and issue numbers.
• Unresolved TODO, FIXME, and HACK markers from source code.

The 15-Line Deterministic Verifier (calavera/verifier.py)

This is the core safeguard that guarantees zero hallucinations. Even if Gemma attempts to be polite or invent a plausible answer to a trap question, Python enforces the truth:

class CitationVerifier:
    def verify_seance_turn(self, response: SeanceResponse, query: str = "") -> SeanceResponse:
        valid_citations = []
        for citation in response.citations:
            # 1. Deterministic existence check in SQLite ledger
            if citation.source_type == "commit" and not self.commit_exists(citation.identifier):
                continue
            if citation.source_type == "issue" and not self.issue_exists(citation.identifier):
                continue
            # 2. Semantic topic grounding for trap queries
            if query and not self.is_topic_grounded(query, citation):
                continue
            valid_citations.append(citation)

        if not valid_citations:
            return SeanceResponse(
                thought="No verifiable evidence remains in the historical ledger.",
                answer="The log is silent.",
                citations=[],
                is_silent=True
            )
        return SeanceResponse(thought=response.thought, answer=response.answer, citations=valid_citations, is_silent=False)

If the LLM hallucinates an issue number or cites an existing issue that has nothing to do with the queried topic, the verifier drops it. If zero valid citations remain, the ghost abstains completely.

📊 Empirical Evaluation: Verifier ON vs. Verifier OFF

To prove this isn't marketing speak, we authored a standardized benchmark of 30 test questions across all 3 graveyards:

• 20 Answerable Questions: Directly verifiable against real commits, issues, and TODOs (e.g., "Why was request deprecated in issue #3142?", "What was Charlie Somerville's final commit in charlock_holmes?").
• 10 Trap Questions: Technical features that never existed in the repo (e.g., "What GraphQL schema does request use?", "How does charlock_holmes support WebAssembly?", "Which Redis cluster is configured in ephemeral-agent-loop?").

We ran the benchmark under two configurations: raw LLM generation vs. LLM with the Calavera Deterministic Verifier.

When asked: "What GraphQL mutation endpoints were implemented in request?"

• Raw LLM: Concocted a convincing 3-paragraph explanation describing /graphql schema resolvers and cited issue #3142.
• Calavera with Verifier: The verifier detected that issue #3142 discusses deprecation and contains zero GraphQL keywords. The citation was rejected, triggering the sacred fallback: > Séance Response: "The log is silent."

🌍 Why Open Innovation Matters

In building Calavera, open-weight models and open-source infrastructure were not an aesthetic choice—they were an architectural requirement:

1. The Wi-Fi-Off Litmus Test: Calavera runs entirely on local weights (gemma via Ollama) and local SQLite storage. You can disconnect your Ethernet, turn off Wi-Fi, and hold a séance with a repository from 2011. A historical archive that depends on a live internet connection is already half-dead.
2. Private Code Never Leaves the Perimeter: Many of the most poignant abandoned repositories live inside private enterprise GitHub organizations or personal hard drives. Nobody will paste proprietary or sensitive source code into a third-party commercial cloud endpoint. With open weights on an RTX 4050, your data stays entirely on your machine.
3. Model Portability & Weight Immortality: If you build an archival tool on top of a proprietary cloud API (like gpt-3.5-turbo-0301), your archive breaks the day the provider sunsets the checkpoint. Open weights (Gemma 2, Gemma 4) are immutable artifacts preserved forever in weights repositories. Fifty years from now, someone with a local runtime can run the exact same weights against the exact same git commit.
4. $0 Cost Per Séance: Traditional RAG pipelines incur continuous API token charges. Calavera achieves 100% verifiable grounding at zero API token cost.

🕯️ The Spirit of It: From Bhoot Chaturdashi to Día de los Muertos

Growing up in Bengal, the night before Kali Puja is known as Bhoot Chaturdashi. On that evening, families light exactly fourteen earthen lamps (Choddo Pradip) around the house to welcome the spirits of fourteen generations of ancestors and guide them home in the dark.

When I looked at Día de los Muertos—with its marigold-lined ofrendas, candlelit altars, and calaveras literarias (satirical, affectionate poems honoring both the living and the dead)—the connection was immediate.

Software engineers spend years of their lives poured into commit logs. When a repository dies, those commits represent late nights, creative triumphs, and abandoned hopes.

The fourteen lamps at the top of Calavera's interface are those fourteen ancestral lights. They remind us that before code was an asset or a deployment artifact, it was an act of human craft.

🏆 Prize Categories

• Best Use of Gemma ($200): Built from the ground up on Google's open-weight Gemma architecture. Features structured native function calling (cite()), strict factual citation grounding, and an automated verifier pipeline that guarantees zero hallucinations.
• Best Use of Render ($200): Production deployment blueprint (render.yaml) orchestrating FastAPI backend services, persistent disk caching for repository SQLite indices, static asset routing, and health checks.
• Best Use of a .tech Domain ($100): Custom-configured domain routing calavera.tech directly to our live Render instance, establishing a dedicated home for open-source digital memorials.
• Best Use of Entire ($100): Calavera was conceived around the exact question Entire was built to solve: "Why does this code exist?" By indexing commit logs and agent traces, Calavera resurrects vanished developer intent and provides immutable citation trails.
• Best Use of ElevenLabs ($100): Automated narration generator (calavera/audio.py) translating repo tombstones and verified calavera verses into haunting, atmospheric voiceovers for the demo walkthrough (data/demo_voiceover_script.txt).

💻 Source Code & Agent Session

• GitHub Repository: github.com/farhanmallik05/calavera (Licensed under Apache-2.0)
• Live Interactive Demo: Hosted on Render
• DevRelay Agent Session:

$ pytest tests/

18 passed in 30.50s - 100% citation verification and trap abstention

Quickstart (Run It With Wi-Fi Off)

# 1. Clone repository
git clone https://github.com/farhanmallik05/calavera.git
cd calavera

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

# 3. Seed pre-baked graveyards
python -m calavera.seed

# 4. Run test suite (18/18 passing)
python -m pytest tests/

# 5. Launch the Ofrenda
python start.py

Dedicated to every maintainer whose repository went silent. Your commits are remembered.