Metadata-Version: 2.4
Name: nexus-ai-fs
Version: 0.10.1
Summary: Nexus = filesystem/context plane.
Author-email: Nexus Team <team@nexus.example.com>
Maintainer-email: Nexus Team <team@nexus.example.com>
License: Apache-2.0
Project-URL: Homepage, https://github.com/nexi-lab/nexus
Project-URL: Documentation, https://nexi-lab.github.io/nexus/
Project-URL: Repository, https://github.com/nexi-lab/nexus
Project-URL: Issues, https://github.com/nexi-lab/nexus/issues
Keywords: filesystem,context,ai,agents,storage,distributed,llm,vector-search,content-addressable
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Filesystems
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.14
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.3.3
Requires-Dist: rich>=15.0.0
Requires-Dist: tqdm>=4.67.3
Requires-Dist: pydantic[email]>=2.13.4
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: jinja2>=3.1.0
Requires-Dist: jsonschema>=4.20.0
Requires-Dist: httpx[http2]>=0.28.1
Requires-Dist: requests>=2.33.1
Requires-Dist: tenacity>=9.1.4
Requires-Dist: aiohttp>=3.13.5
Requires-Dist: frozenlist>=1.8.0
Requires-Dist: protobuf>=6.33.6
Requires-Dist: grpcio>=1.80.0
Requires-Dist: fastapi>=0.136.1
Requires-Dist: uvicorn>=0.46.0
Requires-Dist: python-multipart>=0.0.27
Requires-Dist: watchdog>=6.0.0
Requires-Dist: keyring>=25.7.0
Requires-Dist: sqlalchemy>=2.0.49
Requires-Dist: alembic>=1.18.4
Requires-Dist: greenlet>=3.5.0
Requires-Dist: psycopg2-binary>=2.9.12
Requires-Dist: asyncpg>=0.31.0
Requires-Dist: aiosqlite>=0.22.1
Requires-Dist: cachetools>=7.1.1
Requires-Dist: cachebox>=5.2.3
Requires-Dist: fastbloom-rs>=0.5.10
Requires-Dist: redis>=7.4.0
Requires-Dist: nats-py>=2.14.0
Requires-Dist: authlib>=1.7.2
Requires-Dist: bcrypt>=5.0.0
Requires-Dist: cryptography>=48.0.0
Requires-Dist: PyJWT>=2.12.1
Requires-Dist: pyotp>=2.9.0
Requires-Dist: itsdangerous>=2.2.0
Requires-Dist: tiktoken>=0.12.0
Requires-Dist: markdown-it-py>=4.2.0
Requires-Dist: mdit-py-plugins>=0.6.0
Requires-Dist: fastmcp>=3.2.4
Requires-Dist: pdf-inspector>=0.1.1
Requires-Dist: orjson>=3.11.9
Requires-Dist: pyroaring>=1.1.0
Requires-Dist: blake3>=1.0.8
Requires-Dist: bsdiff4>=1.2.6
Requires-Dist: fastcdc>=1.7.0
Requires-Dist: bm25s>=0.3.8
Requires-Dist: rapidfuzz>=3.14.5
Requires-Dist: lz4>=4.4.5
Requires-Dist: slowapi>=0.1.9
Requires-Dist: limits>=5.8.0
Requires-Dist: prometheus_client>=0.25.0
Requires-Dist: opentelemetry-api>=1.41.1
Requires-Dist: opentelemetry-sdk>=1.41.1
Requires-Dist: opentelemetry-exporter-otlp>=1.41.1
Requires-Dist: opentelemetry-instrumentation-fastapi>=0.62b1
Requires-Dist: opentelemetry-instrumentation-httpx>=0.62b1
Requires-Dist: opentelemetry-instrumentation-sqlalchemy>=0.62b1
Requires-Dist: opentelemetry-instrumentation-redis>=0.62b1
Requires-Dist: opentelemetry-instrumentation-aiohttp-client>=0.62b1
Requires-Dist: aiofiles>=25.1.0
Requires-Dist: structlog>=25.5.0
Provides-Extra: performance
Requires-Dist: fastembed>=0.8.0; extra == "performance"
Requires-Dist: markdown-it-pyrs>=0.4.0; extra == "performance"
Provides-Extra: pay
Requires-Dist: tigerbeetle>=0.17.3; extra == "pay"
Provides-Extra: monitoring
Requires-Dist: psutil>=7.2.2; extra == "monitoring"
Provides-Extra: mobile
Requires-Dist: llama-cpp-python>=0.3.22; extra == "mobile"
Provides-Extra: sandbox-monty
Requires-Dist: pydantic-monty>=0.0.17; extra == "sandbox-monty"
Provides-Extra: sandbox
Requires-Dist: bm25s>=0.3.8; extra == "sandbox"
Requires-Dist: cachetools>=7.1.1; extra == "sandbox"
Requires-Dist: tokenizers>=0.23.1; extra == "sandbox"
Requires-Dist: sqlite-vec>=0.1.9; extra == "sandbox"
Requires-Dist: litellm>=1.83.0; extra == "sandbox"
Requires-Dist: fastembed>=0.8.0; extra == "sandbox"
Provides-Extra: sentry
Requires-Dist: sentry-sdk[fastapi]>=2.59.0; extra == "sentry"
Provides-Extra: profiling
Requires-Dist: pyroscope-io>=1.0.6; extra == "profiling"
Requires-Dist: pyroscope-otel; extra == "profiling"
Provides-Extra: vault
Requires-Dist: hvac>=2.4.0; extra == "vault"
Provides-Extra: aws
Requires-Dist: boto3>=1.43.6; extra == "aws"
Provides-Extra: server-standard
Requires-Dist: uvicorn[standard]>=0.46.0; extra == "server-standard"
Provides-Extra: s3
Requires-Dist: boto3>=1.43.6; extra == "s3"
Provides-Extra: gcs
Requires-Dist: google-cloud-storage>=3.10.1; extra == "gcs"
Requires-Dist: google-auth>=2.52.0; extra == "gcs"
Requires-Dist: google-auth-httplib2>=0.4.0; extra == "gcs"
Provides-Extra: gdrive
Requires-Dist: google-api-python-client>=2.196.0; extra == "gdrive"
Requires-Dist: google-auth>=2.52.0; extra == "gdrive"
Requires-Dist: google-auth-httplib2>=0.4.0; extra == "gdrive"
Requires-Dist: google-auth-oauthlib>=1.4.0; extra == "gdrive"
Provides-Extra: gws
Requires-Dist: google-api-python-client>=2.196.0; extra == "gws"
Requires-Dist: google-auth>=2.52.0; extra == "gws"
Requires-Dist: google-auth-httplib2>=0.4.0; extra == "gws"
Requires-Dist: google-auth-oauthlib>=1.4.0; extra == "gws"
Provides-Extra: slack
Requires-Dist: slack-sdk>=3.41.0; extra == "slack"
Provides-Extra: cloud
Requires-Dist: boto3>=1.43.6; extra == "cloud"
Requires-Dist: google-cloud-storage>=3.10.1; extra == "cloud"
Requires-Dist: google-api-python-client>=2.196.0; extra == "cloud"
Requires-Dist: google-auth>=2.52.0; extra == "cloud"
Requires-Dist: google-auth-httplib2>=0.4.0; extra == "cloud"
Requires-Dist: google-auth-oauthlib>=1.4.0; extra == "cloud"
Requires-Dist: slack-sdk>=3.41.0; extra == "cloud"
Provides-Extra: governance
Requires-Dist: numpy>=2.4.4; extra == "governance"
Requires-Dist: scikit-learn>=1.8.0; extra == "governance"
Requires-Dist: networkx>=3.6.1; extra == "governance"
Requires-Dist: scipy>=1.17.1; extra == "governance"
Provides-Extra: dev
Requires-Dist: pytest>=9.0.3; extra == "dev"
Requires-Dist: pytest-asyncio>=1.3.0; extra == "dev"
Requires-Dist: pytest-cov>=7.1.0; extra == "dev"
Requires-Dist: pytest-mock>=3.15.1; extra == "dev"
Requires-Dist: pytest-benchmark>=5.2.3; extra == "dev"
Requires-Dist: pytest-xdist>=3.8.0; extra == "dev"
Requires-Dist: pytest-timeout>=2.4.0; extra == "dev"
Requires-Dist: freezegun>=1.5.5; extra == "dev"
Requires-Dist: hypothesis>=6.152.4; extra == "dev"
Requires-Dist: syrupy>=5.1.0; extra == "dev"
Requires-Dist: respx>=0.23.1; extra == "dev"
Requires-Dist: ruff>=0.15.12; extra == "dev"
Requires-Dist: mypy>=2.0.0; extra == "dev"
Requires-Dist: pre-commit>=4.6.0; extra == "dev"
Requires-Dist: import-linter>=2.11; extra == "dev"
Requires-Dist: maturin-import-hook>=0.3.0; extra == "dev"
Requires-Dist: mkdocs>=1.6.1; extra == "dev"
Requires-Dist: mkdocs-material>=9.7.6; extra == "dev"
Requires-Dist: mkdocs-git-revision-date-localized-plugin>=1.5.1; extra == "dev"
Requires-Dist: mkdocs-minify-plugin>=0.8.0; extra == "dev"
Requires-Dist: types-pyyaml>=6.0.12.20260408; extra == "dev"
Requires-Dist: types-cachetools>=7.0.0.20260503; extra == "dev"
Requires-Dist: types-requests>=2.33.0.20260503; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=9.0.3; extra == "test"
Requires-Dist: pytest-asyncio>=1.3.0; extra == "test"
Requires-Dist: pytest-cov>=7.1.0; extra == "test"
Requires-Dist: pytest-mock>=3.15.1; extra == "test"
Requires-Dist: pytest-benchmark>=5.2.3; extra == "test"
Requires-Dist: pytest-xdist>=3.8.0; extra == "test"
Requires-Dist: pytest-alembic>=0.12.1; extra == "test"
Requires-Dist: freezegun>=1.5.5; extra == "test"
Requires-Dist: hypothesis>=6.152.4; extra == "test"
Requires-Dist: pydantic-monty>=0.0.17; extra == "test"
Provides-Extra: fuse
Requires-Dist: fusepy>=3.0.1; extra == "fuse"
Provides-Extra: postgres
Requires-Dist: psycopg2-binary>=2.9.12; extra == "postgres"
Provides-Extra: cloud-sql
Requires-Dist: cloud-sql-python-connector[asyncpg]>=1.20.2; extra == "cloud-sql"
Provides-Extra: semantic-search
Requires-Dist: sqlite-vec>=0.1.9; extra == "semantic-search"
Requires-Dist: pgvector>=0.4.2; extra == "semantic-search"
Provides-Extra: semantic-search-remote
Requires-Dist: litellm>=1.83.0; extra == "semantic-search-remote"
Requires-Dist: openai>=2.36.0; extra == "semantic-search-remote"
Provides-Extra: e2b
Requires-Dist: e2b-code-interpreter>=2.6.2; extra == "e2b"
Provides-Extra: docker
Requires-Dist: docker>=7.1.0; extra == "docker"
Provides-Extra: kafka
Requires-Dist: aiokafka>=0.14.0; extra == "kafka"
Provides-Extra: nats-export
Requires-Dist: nats-py>=2.14.0; extra == "nats-export"
Provides-Extra: pubsub
Requires-Dist: gcloud-aio-pubsub>=6.3.0; extra == "pubsub"
Provides-Extra: sse
Requires-Dist: sse-starlette>=3.4.2; extra == "sse"
Provides-Extra: event-streaming
Requires-Dist: aiokafka>=0.14.0; extra == "event-streaming"
Requires-Dist: nats-py>=2.14.0; extra == "event-streaming"
Requires-Dist: gcloud-aio-pubsub>=6.3.0; extra == "event-streaming"
Requires-Dist: sse-starlette>=3.4.2; extra == "event-streaming"
Provides-Extra: all
Requires-Dist: psycopg2-binary>=2.9.12; extra == "all"
Requires-Dist: sqlite-vec>=0.1.9; extra == "all"
Requires-Dist: pgvector>=0.4.2; extra == "all"
Requires-Dist: litellm>=1.83.0; extra == "all"
Requires-Dist: openai>=2.36.0; extra == "all"
Requires-Dist: e2b-code-interpreter>=2.6.2; extra == "all"
Requires-Dist: uvicorn[standard]>=0.46.0; extra == "all"
Requires-Dist: boto3>=1.43.6; extra == "all"
Requires-Dist: google-cloud-storage>=3.10.1; extra == "all"
Requires-Dist: google-api-python-client>=2.196.0; extra == "all"
Requires-Dist: google-auth>=2.52.0; extra == "all"
Requires-Dist: google-auth-httplib2>=0.4.0; extra == "all"
Requires-Dist: google-auth-oauthlib>=1.4.0; extra == "all"
Requires-Dist: slack-sdk>=3.41.0; extra == "all"
Requires-Dist: numpy>=2.4.4; extra == "all"
Requires-Dist: scikit-learn>=1.8.0; extra == "all"
Requires-Dist: networkx>=3.6.1; extra == "all"
Requires-Dist: scipy>=1.17.1; extra == "all"
Dynamic: license-file

<div align="center">

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="assets/logo.png">
  <source media="(prefers-color-scheme: light)" srcset="assets/logo.png">
  <img alt="Nexus" src="assets/logo.png" width="180">
</picture>

### Distributed VFS kernel for multi-agent systems

The infrastructure layer that decides how agents coexist — storage, communication, permissions, coordination.

[![CI](https://github.com/nexi-lab/nexus/actions/workflows/test.yml/badge.svg)](https://github.com/nexi-lab/nexus/actions/workflows/test.yml)
[![PyPI](https://img.shields.io/pypi/v/nexus-ai-fs?color=blue)](https://pypi.org/project/nexus-ai-fs/)
[![nexus-fs](https://img.shields.io/pypi/v/nexus-fs?label=nexus-fs&color=blue)](https://pypi.org/project/nexus-fs/)
[![@nexus-ai-fs/tui](https://img.shields.io/npm/v/@nexus-ai-fs/tui?label=@nexus-ai-fs/tui&color=blue)](https://www.npmjs.com/package/@nexus-ai-fs/tui)
[![Python 3.14+](https://img.shields.io/badge/python-3.14+-3776AB?logo=python&logoColor=white)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-Apache_2.0-blue)](LICENSE)
[![Discord](https://img.shields.io/badge/Discord-community-5865F2?logo=discord&logoColor=white)](https://discord.gg/nexus)

[Documentation](https://nexi-lab.github.io/nexus/) · [Quickstart](https://nexi-lab.github.io/nexus/getting-started/quickstart/) · [Examples](examples/) · [PyPI](https://pypi.org/project/nexus-ai-fs/) · [nexus-fs](https://pypi.org/project/nexus-fs/) · [TUI](https://www.npmjs.com/package/@nexus-ai-fs/tui) · [Roadmap](https://github.com/nexi-lab/nexus/issues)

</div>

---

## Why Nexus exists

The hard problem isn't making one agent work. It's making many agents work together reliably across nodes.

Agent harnesses (LangGraph, CrewAI, AutoGen) decide **what** agents do — tool calls, chains, memory loops. But when agents collaborate, every harness re-invents the same unsolved problems: shared storage, permission boundaries, inter-agent messaging, distributed coordination. And every time, the answers are different, fragile, and non-composable.

Nexus is the layer underneath. A distributed VFS kernel — like Linux for AI agents — that provides the primitives any harness needs but none should build:

**Steering engineering** — infrastructure that sets boundaries and rules so agents operate safely at scale:
- Permission boundaries (ReBAC) — agents only touch what they're allowed to
- IPC primitives (DT_PIPE ~0.5us, DT_STREAM append-only log) — zero-copy inter-agent messaging
- Process isolation (ProcessTable, workspace boundaries) — agent crashes don't cascade
- Distributed coordination (Raft consensus, advisory locks) — multi-node without split-brain

**Context engineering** — infrastructure that gives agents the right information at the right time:
- Unified VFS namespace — all data under one path tree, not scattered APIs
- Semantic search (BM25S + pgvector + section-aware grep) — precise context retrieval
- CAS dedup + content chunking — efficient storage and retrieval at scale
- Federation reads — transparent cross-node data access, agents don't need to know where data lives

**Production distributed topology** — not a single-node toy; a full IT infrastructure for agent organizations:

| Node role | Profile | What it does |
|---|---|---|
| **Hub** | `full` | Central server — Postgres, Dragonfly, all 35+ bricks, auth, search |
| **Worker** | `sandbox` | Agent execution sandbox — SQLite + BM25S, zero external deps |
| **Gateway** | `remote` | Thin RPC client — zero local storage, routes to hub |
| **Auditor** | `cluster` + audit | Centralized audit log — every operation across all nodes |
| **Federation peer** | `cloud` | Full + Raft consensus + multi-tenant — spans data centers |
| **Edge** | `lite` / `embedded` | Pi, Jetson, MCU — local-first with federation sync |

These compose like corporate IT: gateway nodes front the traffic, hubs serve the workload, workers run agents in isolation, auditors watch everything, federation peers replicate across regions. One binary, different profiles.

One interface. Start embedded in a single Python process, scale to a federated cluster across data centers. No code changes.

> *Built by [SudoClaw](https://github.com/nexi-lab) — we focus on making agents deliver quality work, with token economy.*

## Architecture

```
+-----------------------------------------------------------------------+
|  BRICKS (runtime-loadable, 35+)                                       |
|  ReBAC . Auth . Agents . Delegation . Search . Memory . Governance    |
|  Workflows . Pay . MCP . Sandbox . Catalog . Identity . 25+ more      |
+-----------------------------------------------------------------------+
                              | protocol interface
+-----------------------------------------------------------------------+
|  KERNEL (pure Rust, ~5 MB binary)                                     |
|  VFS . Syscall dispatch . Metastore . CAS . Pipes . Streams .        |
|  Lock manager . FileWatcher . Permission gate . Federation (Raft)     |
+-----------------------------------------------------------------------+
                              | dependency injection
+-----------------------------------------------------------------------+
|  DRIVERS (hot-swappable)                                              |
|  redb . PostgreSQL (pgvector) . S3 . GCS . Dragonfly . BM25S . gRPC  |
+-----------------------------------------------------------------------+
```

**Kernel** is pure Rust — a ~5 MB static binary (`nexusd-cluster`) that runs VFS + Raft + IPC + ReBAC + 4-pillar storage with zero Python dependency. It exposes 14 syscalls and never changes.

**Drivers** swap at mount time via `sys_setattr`. Hot-plug any storage backend without restart.

**Bricks** mount and unmount at runtime via `service_enlist` / `service_swap` — like `insmod`/`rmmod` for an AI filesystem.

## Get started in 30 seconds

### Option A: Docker (recommended)

```bash
pip install nexus-ai-fs                       # CLI + SDK
nexus init --preset demo                       # writes nexus.yaml + nexus-stack.yml
nexus up                                       # pulls image, starts Nexus + Postgres + Dragonfly
eval $(nexus env)                              # load connection vars into your shell
```

Open `http://localhost:2026`. That's it.

### Option B: Embedded (no Docker)

```bash
pip install nexus-ai-fs
```

```python
import asyncio, nexus

async def main():
    nx = await nexus.connect(config={"data_dir": "./my-data"})

    await nx.write("/notes/meeting.md", b"# Q3 Planning\n- Ship Nexus 1.0")
    print((await nx.read("/notes/meeting.md")).decode())

    nx.close()

asyncio.run(main())
```

### Option C: CLI

```bash
nexus write /hello.txt "hello world"
nexus cat /hello.txt
nexus ls /
nexus search query "hello" --mode hybrid
nexus grep "TODO" -f "**/*.py"
```

### Terminal UI

```bash
bunx @nexus-ai-fs/tui                                        # connects to localhost:2026
bunx @nexus-ai-fs/tui --url http://remote:2026 --api-key KEY # connect to remote
```

File explorer, API inspector, monitoring dashboard, agent lifecycle management, and more.

## What you get

| Capability | What it does | How agents use it |
|---|---|---|
| **Filesystem** | POSIX-style read/write/mkdir/ls with CAS dedup | Shared workspace — no more temp files |
| **Versioning** | Every write creates an immutable version | Rollback mistakes, diff changes, audit trails |
| **Snapshots** | Atomic multi-file transactions | Commit or rollback a batch of changes together |
| **Search** | BM25S + semantic + hybrid + section-aware grep | Find anything by content, meaning, or structure |
| **Memory** | Persistent agent memory with consolidation + versioning | Remember across runs and sessions |
| **Delegation** | SSH-style agent-to-agent permission narrowing | Safely sub-delegate work with scoped access |
| **ReBAC** | Relationship-based access control (Google Zanzibar model) | Fine-grained per-file, per-agent permissions |
| **MCP** | Mount external MCP servers, expose Nexus as 30+ MCP tools | Bridge any tool ecosystem |
| **Workflows** | Trigger / condition / action pipelines | Automate file processing, notifications, etc. |
| **Governance** | Fraud detection, collusion rings, trust scores | Safety rails for autonomous agent fleets |
| **Pay** | Credit ledger with reserves, policies, approvals | Metered compute for multi-tenant deployments |
| **IPC** | DT_PIPE (FIFO) + DT_STREAM (append-only log) | Sub-microsecond inter-agent messaging |
| **Federation** | Multi-zone Raft consensus with mTLS TOFU | Span data centers without a central coordinator |
| **Sandbox** | Docker-backed execution environments | Isolated code execution per agent |

<details>
<summary><strong>All bricks and system services</strong></summary>

**Bricks (runtime-loadable):** A2A Protocol . Access Manifests . Agent Log . Approvals . Archive . Artifact Index . Auth (API key, OAuth, mTLS) . Catalog (schema extraction) . Context Manifests . Delegation . Discovery . Filesystem . Governance . Identity (DID + credentials) . IPC (pipes + streams) . MCP . Mount . Parsers (50+ formats) . Pay . Portability (import/export) . ReBAC . Reputation . Sandbox (Docker) . Secrets . Search . Share Links (capability URLs) . Snapshots . Task Manager . Tools . Upload (TUS resumable) . Versioning . Watch . Workflows . Workspace

**System services:** Agent Registry . Agent Runtime . Event Bus . Namespace . Scheduler (fair-share, priority tiers)

</details>

## Framework integrations

Every major agent framework works out of the box:

| Framework | What the example shows | Link |
|---|---|---|
| **Claude Agent SDK** | ReAct agent with Nexus as tool provider | [examples/claude_agent_sdk/](examples/claude_agent_sdk/) |
| **OpenAI Agents** | Multi-tenant agents with shared memory | [examples/openai_agents/](examples/openai_agents/) |
| **LangGraph** | Permission-scoped workflows | [examples/langgraph_integration/](examples/langgraph_integration/) |
| **CrewAI** | Multi-agent collaboration on shared files | [examples/crewai/](examples/crewai/) |
| **Google ADK** | Agent Development Kit integration | [examples/google_adk/](examples/google_adk/) |
| **E2B** | Cloud sandbox execution | [examples/e2b/](examples/e2b/) |
| **CLI** | 40+ shell demos covering every feature | [examples/cli/](examples/cli/) |

## Deployment options

| Mode | What | Who it's for |
|---|---|---|
| **Embedded** | `nexus.connect()` — in-process, zero infrastructure | Scripts, notebooks, single-agent apps |
| **Shared daemon** | `nexus init --preset shared && nexus up` | Teams, multi-agent systems, staging |
| **Federation** | Multi-zone Raft consensus across data centers | Production fleets, edge deployments |

### `nexus init` presets

| Preset | Services | Auth | Use case |
|---|---|---|---|
| `local` | None (embedded) | None | Single-process scripts, notebooks |
| `shared` | Nexus + Postgres + Dragonfly | Static API key | Team dev, multi-agent staging |
| `demo` | Same as shared | Database-backed | Demos, seed data, evaluation |

```bash
# Embedded (no Docker)
nexus init                                    # writes nexus.yaml for local embedded mode

# Shared daemon
nexus init --preset shared                    # writes nexus.yaml + nexus-stack.yml
nexus up                                      # pulls image, starts stack, waits for health
eval $(nexus env)                             # load NEXUS_URL, NEXUS_API_KEY, etc.

# Demo with seed data
nexus init --preset demo && nexus up

# Add optional services
nexus init --preset shared --with nats --with mcp --with frontend

# GPU acceleration
nexus init --preset shared --accelerator cuda

# Stack lifecycle
nexus stop                                    # pause containers
nexus start                                   # resume
nexus down                                    # stop and remove
nexus logs                                    # tail logs
nexus restart                                 # down + up
nexus upgrade                                 # pull latest image
```

### Docker image

Published to GHCR (multi-arch: amd64 + arm64):

```
ghcr.io/nexi-lab/nexus:stable          # latest release
ghcr.io/nexi-lab/nexus:edge            # latest develop
ghcr.io/nexi-lab/nexus:<version>       # pinned (e.g. 0.9.3)
ghcr.io/nexi-lab/nexus:stable-cuda     # GPU variant
```

## Storage architecture

Four pillars, separated by access pattern — not by domain:

| Pillar | Interface | Capability | Required? |
|---|---|---|---|
| **Metastore** | `MetastoreABC` | Ordered KV, CAS, prefix scan, optional Raft | Yes — sole kernel init param |
| **ObjectStore** | `ObjectStoreABC` | Streaming blob I/O, petabyte scale | Mounted dynamically |
| **RecordStore** | `RecordStoreABC` | Relational ACID, JOINs, vector search | Services only — optional |
| **CacheStore** | `CacheStoreABC` | Ephemeral KV, pub/sub, TTL | Optional (defaults to null) |

The kernel starts with just a Metastore. Everything else is layered on without changing a line of kernel code.

## Performance

### Agent-level: context engineering

Nexus Dynamic Discovery vs loading all tools into the LLM context (POC on [BFCL benchmark](https://gorilla.cs.berkeley.edu/leaderboard.html)):

| Metric | Static (all tools in context) | Nexus Dynamic Discovery |
|---|---|---|
| Irrelevance detection accuracy | 40-80% | **100%** |
| Token consumption (65 tools) | ~276K | **~61K (78% reduction)** |
| Hallucination on irrelevant tools | frequent | **zero** |
| ECCA-R (cost per reliable answer) | high | **2x better** |

Dynamic Discovery only loads relevant tools on demand via score-based search, so the LLM sees a clean context instead of 65+ tool definitions. Details: [nexus-benchmarks](https://github.com/nexi-lab/nexus-benchmarks).

### Kernel-level: steering overhead is negligible

Kernel syscall latency (pure Rust, PathLocal + redb, Apple M-series):

| Syscall | Latency | What's included |
|---|---|---|
| `sys_stat` | **~727 ns** | redb lookup + permission lease check |
| `sys_read` 1 KB | **~3.4 us** | permission + CAS resolve + hook dispatch + I/O |
| `sys_readdir` 100 entries | **~68 us** | metastore + backend merge |
| `sys_rename` | **~6.6 us** | atomic metastore + backend |

The full steering stack (permission check, CAS resolution, hook dispatch, metastore lookup) adds < 2 us to a read. An LLM call takes 100-1000 ms. The infrastructure is invisible at agent-interaction timescales.

## Requirements

- **Python 3.14+** for the SDK and CLI
- **Rust toolchain** only needed for building from source (the Docker image and `nexusd-cluster` binary ship pre-built)

## Contributing

```bash
git clone https://github.com/nexi-lab/nexus.git && cd nexus
uv python install 3.14
uv sync --extra dev --extra test
uv run pre-commit install
uv run pytest tests/
```

For semantic search work: `uv sync --extra semantic-search`

Claude Code users: see `CLAUDE.md` (local-only, not committed) for the full contributor guide.

## Troubleshooting

<details>
<summary><code>ModuleNotFoundError: No module named 'nexus'</code></summary>

Install from PyPI: `pip install nexus-ai-fs`. The package name on PyPI is `nexus-ai-fs`, not `nexus`.

</details>

## License

Apache License 2.0 — see [LICENSE](LICENSE) for details.

Built by [Nexi Labs](https://github.com/nexi-lab).
