Metadata-Version: 2.4
Name: kdg-nexus
Version: 0.1.1
Summary: Nexus OS - Local-first AI privacy gateway for enterprise developer workflows
Author: Ayushman Mukherjee
License-Expression: MIT
Project-URL: Homepage, https://github.com/ayush585/KDG
Project-URL: Repository, https://github.com/ayush585/KDG
Project-URL: Issues, https://github.com/ayush585/KDG/issues
Keywords: ai,privacy,developer-tools,secrets,redaction,audit
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.115.0
Requires-Dist: uvicorn[standard]>=0.30.0
Requires-Dist: pydantic>=2.8.0
Requires-Dist: pyyaml>=6.0.1
Requires-Dist: httpx>=0.27.0
Requires-Dist: anthropic>=0.34.0
Requires-Dist: openai>=1.0.0
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: ruff>=0.5.0; extra == "dev"
Provides-Extra: release
Requires-Dist: build>=1.2.0; extra == "release"
Requires-Dist: twine>=5.0.0; extra == "release"
Dynamic: license-file

# 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

```text
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
- 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
- Local hybrid repository indexing, secure scan, human approval plan, and redacted patch preview workflow
- Repository API protected by `X-Nexus-Token`
- 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:

```bash
pip install kdg-nexus
nexus --version
nexus --help
```

For local development from this repository:

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

For local inference:

```bash
ollama serve
ollama pull llama3.2:3b
```

Set the model in `.env` when needed:

```env
NEXUS_OLLAMA_MODEL=llama3.2:3b
```

Start the daemon:

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

Health check:

```bash
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
powershell -ExecutionPolicy Bypass -File scripts\run_judge_demo.ps1
```

Then follow [docs/JUDGE_DEMO.md](docs/JUDGE_DEMO.md).

Build the extension:

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

Start the real daemon before the live demo:

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

Launch the Extension Development Host:

```powershell
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:

```bash
pytest -q
```

## API example

```bash
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?"
  }'
```

## Recommended Demo Flow

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

```bash
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`](docs/architecture/REPOSITORY_INDEXING_ARCHITECTURE.md).  
Measured local benchmarks: [`benchmarks/README.md`](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
