kdg-nexus 0.1.0

Nexus OS - Local-first AI privacy gateway for enterprise developer workflows

Nexus OS

A local-first AI egress gateway for source code.

Nexus sits between a developer workflow and AI coding models. It inspects each request locally, removes secrets, pseudonymizes proprietary Python identifiers, chooses a local, sanitized-cloud, or blocked route, and records a tamper-evident audit event.

Current scope: a Python/FastAPI daemon, CLI, privacy pipeline, Ollama adapter, Groq/Anthropic cloud adapters, automated tests, and a VS Code/Cursor Command Center extension.

Core flow

Developer request
  -> secret scan
  -> Python AST symbol extraction
  -> semantic pseudonymization
  -> YAML policy evaluation
  -> route: local_only | sanitized_cloud | blocked
  -> exact egress verification before cloud use
  -> local de-tokenization of the model response
  -> hash-chained audit event

Why it exists

Developers in regulated or IP-sensitive environments often face a bad trade-off:

• use a strong cloud model and expose sensitive context;
• use a small local model and lose capability;
• manually scrub every prompt and slow down the workflow.

Nexus treats privacy as a routing and verification problem instead of forcing one model choice for every request.

Current capabilities

• Regex and entropy-based secret detection
• Python AST symbol extraction
• Semantic identifier pseudonymization
• YAML policy engine
• Local-only, sanitized-cloud, and blocked routes
• Ollama local inference
• Groq / Anthropic sanitized-cloud adapters with exact egress verification
• Tamper-evident audit ledger with Phase 3 truthful egress receipts
• Local hybrid repository indexing (search + repo assist)
• Repository API protected by X-Nexus-Token
• Groq and Anthropic provider adapters
• Local response de-tokenization
• SQLite hash-chained audit ledger with Phase 3 truthful egress receipts (intended vs actual provider/route, call attempts, payload hash — never raw code/secrets/maps)
• Request-scoped exact outbound payload inspection (token-gated short-lived lookup)
• VS Code/Cursor Command Center extension with live secure assist and fixture modes
• Repo-wide secure scan, human approval plan, and redacted patch preview workflow
• Dependency/generated artifact filtering for repo scans (node_modules, lockfiles, build output, caches)
• nexus audit verify and nexus audit list
• FastAPI endpoints for assist, redact, route, health, audit verification, and repository indexing/search/remediation
• Local hybrid repository indexing (SQLite + FTS5) with CLI nexus repo … commands

Important limitations

This is a hackathon prototype, not a production security boundary.

• It is a local daemon, not an operating-system kernel.
• Python is the only AST-aware language currently supported.
• Secret detection is heuristic and cannot guarantee detection of every sensitive value.
• The current hash chain is tamper-evident, not independently signed.
• OS-wide or network-wide enforcement is future work.
• The extension is an MVP demo surface, not a production policy enforcement layer.

Setup

Requires Python 3.11+.

Install from PyPI after the first release:

pip install kdg-nexus
nexus --version
nexus --help

For local development from this repository:

python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
cp .env.example .env

For local inference:

ollama serve
ollama pull llama3.2:3b

Set the model in .env when needed:

NEXUS_OLLAMA_MODEL=llama3.2:3b

Start the daemon:

uvicorn nexus.main:app --host 127.0.0.1 --port 7420

Health check:

curl http://127.0.0.1:7420/v1/health

VS Code / Cursor extension demo

The extension has two modes:

• Live (default): calls the local Nexus daemon, keeps the local Nexus token in the extension host, and shows real request evidence.
• Fixture: uses built-in UI fixtures for offline Command Center review.

For the judge-ready live path, run:

powershell -ExecutionPolicy Bypass -File scripts\run_judge_demo.ps1

Then follow docs/JUDGE_DEMO.md.

Build the extension:

cd extension
npm install
cd webview-ui
npm install
cd ..
npm run build

Start the real daemon before the live demo:

python -m uvicorn nexus.main:app --host 127.0.0.1 --port 7420

Launch the Extension Development Host:

code --extensionDevelopmentPath=C:\Users\mukhe\KDG\extension C:\Users\mukhe\KDG

In the Extension Development Host:

1. Open a Python file containing synthetic sensitive code.
2. Select the code, or leave the selection empty to use a bounded current-file excerpt.
3. Run Nexus: Ask Privately.
4. Enter a question, for example: The intended multiplier is 1.25. Return corrected Python code containing the class and function names.
5. Confirm the restored answer appears in Command Center.
6. Verify the Live badge plus request evidence: route, provider, real event timeline, exact sanitized outbound payload, receipt, and audit verification.

To use fixtures instead, set nexus.mode to fixture in VS Code settings and open Nexus: Open Command Center.

For larger codebases, run Nexus: Scan Codebase Privately from the Command Palette. Nexus registers and indexes the open workspace locally, ranks candidate files from indexed secret fingerprints, diagnostics, test-output hints, the focus query, and the active editor path as ranking context. It then asks you to approve exact indexed files from a picker before patch preview. The preview report uses redacted diffs and never writes source files automatically.

For a richer masking demo, open demo-repo/customer_support/secure_ticket_service.py. It contains only synthetic fake credentials, fake personal data, normal code, and small logic bugs. Use the prompt in demo-repo/README.md to verify that secrets and personal data are removed before sanitized cloud assist.

Run tests:

pytest -q

API example

curl -X POST http://127.0.0.1:7420/v1/assist \
  -H "Content-Type: application/json" \
  -d '{
    "code": "def calculate_internal_risk_score_for_loan_default(x):\n    return x * 2",
    "file_path": "payments/risk_engine.py",
    "diagnostics": [],
    "test_output": null,
    "question": "Why is this calculation failing?"
  }'

Hackathon winning path

The next work should happen in this order:

1. Close egress gaps: sanitize and verify code, question, diagnostics, and test output as one exact outbound payload.
2. Add deterministic prompt-injection blocking: demonstrate that a request to reveal redacted values makes no cloud call.
3. Make the audit receipt truthful: hash the exact outbound prompt, expose provider, policy hits, leakage status, latency, and whether a network call occurred.
4. Harden the VS Code extension: add packaged install flow, richer error handling, and repeatable UI automation.
5. Add a golden demo: a realistic fintech bug is fixed after sanitization and the test passes.
6. Benchmark utility and latency: compare raw cloud, Nexus sanitized cloud, and Nexus local-only using project-generated numbers only.

Demo story

1. Show a normal AI request that would expose a fake credential and proprietary identifiers.
2. Send the same request through Nexus and open the exact outbound payload.
3. Receive a cloud-generated fix, restore the real names locally, and pass the failing test.
4. Attempt prompt injection and show that no cloud request is made.
5. Run nexus audit verify, then demonstrate detection on a deliberately tampered copy.

CLI

nexus audit list
nexus audit verify

# Repository indexing (Phase 2.5)
nexus repo register /path/to/your/repo
nexus repo index <repo_id>
nexus repo search <repo_id> "symbol_or_query" --json
nexus repo list
nexus repo status <repo_id>

Repository indexing (Phase 2.5)

Nexus can index local repositories into isolated SQLite + FTS5 databases under ~/.nexus/indexes/ (override with NEXUS_INDEX_DB_ROOT). Search and context retrieval run entirely on your machine — no model or network calls.

Endpoint	Purpose
POST /v1/repos	Register a local path
GET /v1/repos	List repositories
GET /v1/repos/{repo_id}	Index status
POST /v1/repos/{repo_id}/index	Build or update ({"full": true} for full rebuild)
POST /v1/repos/{repo_id}/search	Hybrid search (no model)
POST /v1/repos/{repo_id}/scan	Safe repo-wide remediation candidate scan (no model)
POST /v1/repos/{repo_id}/fix-plan	Human approval plan for candidate files (no model)
POST /v1/repos/{repo_id}/patch-preview	Redacted, non-writing patch previews for approved files
POST /v1/repos/{repo_id}/assist	Context pack → recovery guard → privacy pipeline

Privacy notes:

• Secrets are never stored raw in the index — only redacted chunks and HMAC-SHA256 fingerprints (key at ~/.nexus/fingerprint_key).
• /v1/repos* requires a local API token via X-Nexus-Token (stored at ~/.nexus/api_token). CORS is explicit loopback origins only (no *).
• Git discovery includes tracked and untracked non-ignored files (git ls-files -co --exclude-standard).
• Dependency/generated artifacts are excluded from remediation candidates by default, including common package lockfiles, build output, caches, and node_modules.
• full=true reprocesses every file; config drift requires a full rebuild.
• Oversized files are partially indexed with bounded streaming and coverage stats.
• /v1/repos/{id}/search never calls a provider.
• /v1/repos/{id}/assist re-reads selected spans from disk, runs the recovery guard, then applies the sanitize/egress pipeline.
• Index builds run as background jobs (per-repo lock); poll GET /v1/repos/{id} for readiness.

Architecture: docs/architecture/REPOSITORY_INDEXING_ARCHITECTURE.md.
Measured local benchmarks: benchmarks/README.md.

Limitations (indexing v1)

Python gets AST-aware chunking; other languages use line windows. Retrieval uses import-graph one-hop expansion (no call-graph). Semantic/vector search is optional and off by default. This is a local hybrid indexer — not a claim of parity with proprietary code-search products.

Security

Never commit .env, API keys, generated databases, or real proprietary code. The committed demo fixtures contain fake values only.

Phase 4/5 additions

• Typed provider errors and fallback state machine (docs/architecture/PROVIDER_FAILURE_STATE_MACHINE.md)
• Execution event stream (docs/architecture/EXECUTION_EVENT_STREAM.md)
• Report: docs/reports/PHASE_4_5_PROVIDER_LIFECYCLE_REPORT.md