DEV Community: Tyler H

NeuroGuard: AI-Native Code Security Using Gemma 4's Glass-Box Thinking Mode

Tyler H — Wed, 13 May 2026 10:00:38 +0000

Submitted to the Build With Gemma 4 track of the Dev.to Google Gemma 4 Challenge.

TL;DR: I built neuroguard — a CLI that uses Gemma 4's ThinkingConfig(include_thoughts=True) API to stream the model's full cognitive trace in a split-pane terminal UI while it finds security vulnerabilities and produces a SAST-verified secure rewrite. Live demo → | Install: pip install neuroguard-ai | Source: github.com/tyy130/neuroguard-ai.

The Problem I Kept Running Into

security
Studies find the majority of AI-generated applications ship to production with OWASP Top 10 vulnerabilities. I've seen it firsthand. The worst cases aren't SQL injections from typos — they're hallucinated bypasses: an AI agent removes authentication middleware to resolve a compilation error, silently stripping the application of its entire security layer.

The frustrating thing is that a human reviewer wouldn't make this mistake, because they'd reason about what the code does before deleting it. The AI just optimized for "code compiles" without the security reasoning step.

The root cause is opacity. When a black-box LLM generates insecure code, you can't see why. You get the output without the reasoning. And without the reasoning, you can't tell if the model considered security at all — or silently decided to ignore it.

I wanted to fix that.

What Makes Gemma 4 Different

Two approaches existed before Gemma 4:

Hidden (OpenAI o1/o3): These models run a real reasoning process, but the trace is completely invisible. You get a reasoning_tokens count in the usage object, nothing else. You can't route it, log it, or build on top of it.
Inline text (local R1, prompted CoT): When you run a reasoning model locally — like R1 via Ollama — or prompt any model to think step by step, the reasoning ends up in the same string as the response, separated only by <think>...</think> tags. You can see it, but you have to parse it out. Tags can split across stream chunks, the model can reopen reasoning after </think>, and there's no API-level guarantee about the boundary.

Gemma 4 does something different. ThinkingConfig(include_thoughts=True) emits reasoning as structurally separate stream parts — each chunk carries a thought=True field. The reasoning and the response are separated at the API level, not by text parsing.

That API-level separation is what makes NeuroGuard possible. I can route thought parts to a left pane and response parts to a right pane in real-time, with no regex parsing, no risk of the boundary getting confused, no thought tokens leaking into the final output.

How NeuroGuard Works

┌─────────────────────────────┬────────────────────────────┐
│  🧠 Gemma 4 Thinking        │  🔒 Secure Rewrite         │
│  ─────────────────────────  │  ─────────────────────────  │
│  ...the SQL query on line   │                             │
│  47 concatenates user input │                             │
│  directly. This is a        │                             │
│  classic injection vector.  │                             │
│  The fix is parameterized   │                             │
│  queries...                 │  from flask import Flask   │
│                             │  import sqlite3            │
│  ...the eval() on line 62   │                             │
│  executes arbitrary strings │  def get_user(user_id):    │
│  from the request body.     │      conn = sqlite3.connect│
│  This is RCE...             │      cursor.execute(       │
│                             │          "SELECT * FROM    │
│                             │           users WHERE      │
│                             │           id = ?", (id,))  │
└─────────────────────────────┴────────────────────────────┘
  Bandit: 4 findings → ✓ CLEAN (0 findings in rewrite)

The left pane streams as Gemma 4 reasons. The right pane fills in as it produces the secure rewrite. Bandit runs on the rewrite at the end and confirms the fix is real.

The Core API Call

response = client.models.generate_content_stream(
    model="gemma-4-31b-it",
    contents=[types.Content(role="user", parts=[types.Part(text=prompt)])],
    config=types.GenerateContentConfig(
        system_instruction=SYSTEM_PROMPT,
        thinking_config=types.ThinkingConfig(
            include_thoughts=True,
            thinking_budget=thinking_budget,  # scales with SAST severity
        ),
    ),
)

for chunk in response:
    for part in chunk.candidates[0].content.parts:
        if getattr(part, "thought", False):
            yield f"<think>{part.text}"   # → left pane
        elif part.text:
            yield part.text               # → right pane

That's it. No regex. No text parsing. The thought=True flag on stream parts is the entire separation mechanism.

Making the Thinking Load-Bearing

The key design decision was making the thinking trace load-bearing, not decorative. I inject SAST findings from Bandit/semgrep directly into the prompt before the model starts reasoning:

SAST pre-scan findings (ground truth — confirm or refute each in your reasoning):

  [HIGH] B608 hardcoded_sql_expressions — line 47
  [HIGH] B307 eval() — line 62
  [MEDIUM] B105 hardcoded_password_string — line 12

Now the model's thinking trace is explicitly reasoning about concrete, tool-verified findings. It can't skip them. It either confirms the finding and fixes it, or explains why it's a false positive. Either way, you have an auditable chain of evidence tied to specific lines.

The thinking budget scales automatically: 4096 + HIGH_count × 512 + MEDIUM_count × 256 tokens (capped at 16384). Files with more HIGH findings get proportionally deeper reasoning.

What It Looks Like in Practice

The built-in demo (demo/vuln_sample.py) is a Flask app with 5 intentional vulnerabilities:

# demo/vuln_sample.py — intentionally vulnerable

SECRET_KEY = "supersecret123"   # hardcoded secret

@app.route("/admin")            # no auth check
def admin_panel():
    return "Admin panel"

@app.route("/user")
def get_user():
    user_id = request.args.get("id")
    query = f"SELECT * FROM users WHERE id = {user_id}"  # SQL injection
    ...

@app.route("/eval")
def run_code():
    code = request.args.get("code")
    return str(eval(code))      # RCE

Running neuroguard review demo/vuln_sample.py:

Bandit finds 4 HIGH/MEDIUM findings in the original
Those findings are injected into the prompt
Gemma 4 streams its reasoning — you watch it identify the injection vector, explain the attack path, and reason through the fix
The secure rewrite uses parameterized queries, removes eval(), moves the secret to env vars
Bandit runs on the rewrite: 0 findings

The thinking trace is the proof of work. You don't have to trust the rewrite blindly — you can see the exact chain of reasoning that produced it.

SAST + LLM: Two Layers of Confidence

One thing I deliberately avoided was making this "just an LLM." Bandit (for Python) and semgrep/regex patterns (for JS/TS) run before the model sees the code. The findings are facts fed into the reasoning layer.

After the rewrite, they run again. The exit code is non-zero if the original had HIGH/MEDIUM findings — so in CI/CD, your pipeline fails on vulnerable code:

# .github/workflows/neuroguard.yml
- name: Security review
  run: neuroguard review src/ --format json
  env:
    GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}

You can also get a Slack notification with Gemma 4's reasoning excerpt, post a GitHub PR comment automatically, or pipe JSON to any webhook:

neuroguard review app.py --notify-slack https://hooks.slack.com/...
neuroguard review app.py --format json | jq '.thinking' | head -20

The Architecture

neuroguard/
├── agent.py           # Gemma 4 streaming client — ThinkingConfig, retry/fallback
├── thinking_parser.py # Routes <think> parts to left pane, response to right
├── prompts.py         # Language-aware prompt + SAST findings injection
├── cli.py             # Typer CLI: review, install-hooks, --format json/text
├── integrations.py    # Slack Block Kit, webhook, GitHub PR comments
├── tools/
│   ├── sast.py        # Bandit wrapper → Python findings
│   └── js_sast.py     # semgrep + regex fallback → JS/TS findings
└── ui.py              # Rich split-pane Live layout (12fps)

Model fallback: If the 31B dense model hits a rate limit, NeuroGuard falls back to gemma-4-26b-a4b-it (MoE, ~4B active params) automatically. The demo never stalls.

Language support: Python, JavaScript, TypeScript, JSX, TSX.

Try It

pip install neuroguard-ai
export GEMINI_API_KEY=your_key   # free at https://aistudio.google.com/apikey

# against your own code
neuroguard review app.py

# against the built-in vulnerable demo
git clone https://github.com/tyy130/neuroguard-ai
cd neuroguard-ai
neuroguard review demo/vuln_sample.py

You'll see Gemma 4's full reasoning trace in real-time, then a clean, Bandit-verified secure rewrite.

Why This Matters Beyond the Demo

The shift happening in software development right now is that AI generates the first draft of most code. That's not going to stop. But "vibe coding" — accepting AI output without verification — is already producing an epidemic of OWASP vulnerabilities in production systems.

The answer isn't to distrust AI-generated code. It's to demand transparency from the model before you trust the output. Gemma 4's Thinking Mode makes that possible at the API level for the first time.

NeuroGuard is a concrete demonstration of what that looks like: the model can't silently delete an auth check if its reasoning is visible. The audit trail is the security control.

Apache 2.0. The Kaggle weights mean you can run this on-premise — no code ever leaves your network.

Links:

GitHub: github.com/tyy130/neuroguard-ai
PyPI: pypi.org/project/neuroguard-ai
Landing page: neuroguard-psi.vercel.appgemmachallenge

Notion Cortex: A Multi-Agent AI Research System Where Notion Is the Operating System

Tyler H — Tue, 31 Mar 2026 21:51:17 +0000

This is a submission for the Notion MCP Challenge

What I Built

Notion Cortex is a multi-agent AI research system that uses Notion as its operating system — not just an output destination, but the shared coordination layer where agents think, communicate, and await human approval.

Give it any topic, and five specialized AI agents fan out in parallel:

Scout agents (x5) research different angles simultaneously, extracting structured entities into a Knowledge Graph
Analyst cross-references all findings, identifies patterns and gaps
Synthesizer streams a structured synthesis directly into Notion as it thinks
Approval Gate pauses execution and waits for you to review in Notion — set Status to "Approved" to continue
Writer produces a publication-ready intelligence brief with headings, entity tables, and conclusions

Every agent's reasoning streams into its own Working Memory page in real time. You can literally watch them think in Notion.

$ notion-cortex "The rise of autonomous AI agents in software engineering"

🧠 Notion Cortex — starting run for: "The rise of autonomous AI agents..."

📋 Bootstrapping Notion workspace...
✅ Workspace ready (1.6s)

🧩 Decomposing topic into research angles...
   5 angles identified

🚀 Running 5 Scout agents (concurrency: 3)...
  ✅ Scout 1 done
  ✅ Scout 2 done
  ...

📊 All Scouts complete (103s). Running Analyst...
✅ Analyst done (31s)

🕸️  Computing knowledge graph relations...
✅ Relations linked (8s)

🔗 Running Synthesizer...
✅ Synthesis written (23s)

✍️  Running Writer...
✅ Writer done (43s)

🎉 Done in 229s! Intelligence brief: https://notion.so/...

Video Demo

The demo shows a complete run from notion-cortex "topic" through all 5 agent phases to the final intelligence brief in Notion.

Show us the code

GitHub: github.com/tyy130/notion-cortex

Architecture

src/
  index.ts              CLI entry point + setup wizard
  cleanup.ts            Archives all cortex-* databases for a fresh start
  orchestrator.ts       Pipeline coordinator
  llm.ts                Dual-provider streaming (OpenAI + Anthropic)
  streaming.ts          Token buffer → timed Notion block flush
  concurrency.ts        Write queue (p-limit) + exponential backoff retry
  types.ts              Zod schemas for all database entry types
  agents/
    scout.ts            Research + entity extraction via MCP
    analyst.ts          Cross-scout analysis + KG enrichment
    synthesizer.ts      Structured synthesis streamed to Working Memory
    writer.ts           Final brief written to Outputs database
  notion/
    bootstrap.ts        Idempotent 5-database workspace creation
    client.ts           Notion SDK singleton
    mcp-client.ts       Notion MCP server (stdio transport)
    task-bus.ts         Agent task queue CRUD
    working-memory.ts   Streaming page writer + content reader
    knowledge-graph.ts  Entity store with serialized upsert
    approval-gates.ts   Human-in-the-loop polling
    outputs.ts          Final page publisher
    markdown-blocks.ts  Markdown → Notion block converter
    utils.ts            Shared helpers

Key Technical Decisions

Serialized KG upsert: Parallel scouts can discover the same entity simultaneously. A pLimit(1) queue wraps the check-then-create operation, making the upsert atomic without a database lock.

Two-queue concurrency design: writeQueue (pLimit(3)) handles Notion API rate limiting. kgUpsertQueue (pLimit(1)) handles logical atomicity. Different concerns, different queues.

Idempotent bootstrap with archived filtering: bootstrapWorkspace searches for existing cortex-* databases and reuses them. It filters out archived databases (Notion's search API returns them by default) and uses databases.update to ensure schema migrations apply to pre-existing databases.

Dual-provider LLM abstraction: Supports OpenAI (default) and Anthropic with streaming and multi-turn tool-use loops. Switch with one env var.

55 tests across 13 files: Full coverage of the orchestrator pipeline, all agents, concurrency utilities, markdown converter, and Notion data layer.

Quick Start

git clone https://github.com/tyy130/notion-cortex.git
cd notion-cortex
npm install
notion-cortex setup    # interactive wizard
notion-cortex "your research topic"

How I Used Notion MCP

Notion isn't just where output ends up — it's the runtime substrate. The Notion MCP server (@notionhq/notion-mcp-server) runs as a stdio subprocess, giving Scout agents access to notion_search — they check what knowledge already exists in the workspace before extracting new entities, avoiding redundant work across runs.

Beyond MCP search, each database works as infrastructure through the Notion SDK:

1. Task Bus (agent coordination)

The orchestrator creates tasks, scouts claim them via assigned_agent, and status transitions (pending → active → done → blocked) drive the pipeline forward. This is a distributed task queue implemented entirely in Notion.

2. Working Memory (streaming scratchpad)

Each agent gets a dedicated Notion page. As tokens stream from the LLM, a timed buffer flushes them as paragraph blocks to the page every second. You can open a scout's Working Memory page and watch it think in real time.

3. Knowledge Graph (structured entity store)

Scouts extract entities (companies, products, trends, concepts) with claims, confidence levels, and source URLs. A serialized upsert queue (pLimit(1)) prevents duplicate entities when parallel scouts find the same thing. After the Analyst pass, computeAndStoreRelations scans all entities and auto-links them using Notion's relation property — if "GitHub Copilot" appears in another entity's claim, they get linked.

4. Approval Gates (human-in-the-loop)

Before the Writer runs, an approval gate creates a Notion database entry with status "Pending" and a link to the synthesis. The system polls with exponential backoff until you change the status to "Approved" or "Rejected" in Notion. This is genuine human-in-the-loop control — not a dialog box, but a Notion workflow.

5. Outputs (final deliverables)

The Writer converts its markdown output into native Notion blocks — headings, bullet lists, numbered lists, tables, code blocks, bold/italic, and links — using a custom markdownToNotionBlocks converter. The result is a proper Notion page, not a pasted text blob.

Final Thoughts

The most surprising thing about this project was how naturally Notion works as an agent coordination layer. Databases become task queues. Pages become working memory. Relations become a knowledge graph. Status properties become approval gates. It's not a hack — it's genuinely the right tool for this.

The human-in-the-loop approval gate is my favorite feature. Most agent systems are either fully autonomous or require you to babysit a terminal. With Cortex, you get a Notion notification, review the synthesis at your own pace, and approve when ready. The agents wait patiently.

MIT licensed. PRs welcome.