Metadata-Version: 2.4
Name: nexus-ai-fs
Version: 0.9.8
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.12
Classifier: Programming Language :: Python :: 3.13
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.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.1.7
Requires-Dist: rich>=13.7.0
Requires-Dist: tqdm>=4.66.0
Requires-Dist: pydantic>=2.5.0
Requires-Dist: pyyaml>=6.0.1
Requires-Dist: httpx[http2]>=0.28.1
Requires-Dist: requests>=2.31.0
Requires-Dist: tenacity>=8.2.0
Requires-Dist: aiohttp>=3.11.0
Requires-Dist: frozenlist>=1.5.0
Requires-Dist: protobuf>=6.31.1
Requires-Dist: grpcio>=1.76.0
Requires-Dist: fastapi>=0.124.0
Requires-Dist: uvicorn[standard]>=0.38.0
Requires-Dist: uvloop>=0.22.1; sys_platform != "win32"
Requires-Dist: watchfiles>=1.0.0
Requires-Dist: sqlalchemy>=2.0.44
Requires-Dist: alembic>=1.13.0
Requires-Dist: greenlet>=3.0.0
Requires-Dist: psycopg2-binary>=2.9.10
Requires-Dist: asyncpg>=0.31.0
Requires-Dist: aiosqlite>=0.20.0
Requires-Dist: cachetools>=6.2.2
Requires-Dist: redis>=7.0.0
Requires-Dist: nats-py>=2.9.0
Requires-Dist: authlib>=1.6.5
Requires-Dist: bcrypt>=4.0.0
Requires-Dist: cryptography>=41.0.0
Requires-Dist: PyJWT>=2.8.0
Requires-Dist: boto3>=1.42.4
Requires-Dist: google-cloud-storage>=3.6.0
Requires-Dist: google-api-python-client>=2.187.0
Requires-Dist: google-auth>=2.43.0
Requires-Dist: google-auth-httplib2>=0.2.1
Requires-Dist: google-auth-oauthlib>=1.2.0
Requires-Dist: slack-sdk>=3.39.0
Requires-Dist: tiktoken>=0.12
Requires-Dist: dotenv>=0.9.9
Requires-Dist: fastmcp>=2.0.0
Requires-Dist: markitdown[all]>=0.1.0; python_version < "3.14"
Requires-Dist: orjson>=3.10.0
Requires-Dist: pyroaring>=1.0.0
Requires-Dist: blake3>=1.0.0
Requires-Dist: bsdiff4>=1.2.0
Requires-Dist: fastcdc>=1.5.0
Requires-Dist: bm25s>=0.2.0
Requires-Dist: rapidfuzz>=3.0.0
Requires-Dist: lz4>=4.3.0
Requires-Dist: slowapi>=0.1.9
Requires-Dist: limits>=3.6.0
Requires-Dist: prometheus_client>=0.20.0
Requires-Dist: opentelemetry-api>=1.20.0
Requires-Dist: opentelemetry-sdk>=1.20.0
Requires-Dist: opentelemetry-exporter-otlp>=1.20.0
Requires-Dist: opentelemetry-instrumentation-fastapi>=0.41b0
Requires-Dist: opentelemetry-instrumentation-httpx>=0.41b0
Requires-Dist: opentelemetry-instrumentation-sqlalchemy>=0.41b0
Requires-Dist: opentelemetry-instrumentation-redis>=0.41b0
Requires-Dist: opentelemetry-instrumentation-aiohttp-client>=0.41b0
Requires-Dist: numpy>=1.26.0
Requires-Dist: scikit-learn>=1.4.0
Requires-Dist: aiofiles>=25.1.0
Requires-Dist: structlog>=24.4.0
Requires-Dist: networkx>=3.2
Requires-Dist: scipy>=1.11.0
Provides-Extra: performance
Requires-Dist: fastembed>=0.4.0; extra == "performance"
Provides-Extra: compression
Requires-Dist: zstandard>=0.22.0; extra == "compression"
Provides-Extra: monitoring
Requires-Dist: psutil>=5.9; extra == "monitoring"
Provides-Extra: mobile
Requires-Dist: llama-cpp-python>=0.2.0; extra == "mobile"
Provides-Extra: sandbox-monty
Requires-Dist: pydantic-monty>=0.0.4; extra == "sandbox-monty"
Provides-Extra: sentry
Requires-Dist: sentry-sdk[fastapi]>=2.0.0; extra == "sentry"
Provides-Extra: profiling
Requires-Dist: pyroscope-io>=0.8.16; extra == "profiling"
Requires-Dist: pyroscope-otel; extra == "profiling"
Provides-Extra: dev
Requires-Dist: pytest>=9.0.2; extra == "dev"
Requires-Dist: pytest-asyncio>=1.3.0; extra == "dev"
Requires-Dist: pytest-cov>=7.0.0; extra == "dev"
Requires-Dist: pytest-mock>=3.12.0; extra == "dev"
Requires-Dist: pytest-benchmark>=4.0.0; extra == "dev"
Requires-Dist: pytest-xdist>=3.8.0; extra == "dev"
Requires-Dist: pytest-timeout>=2.3.0; extra == "dev"
Requires-Dist: freezegun>=1.4.0; extra == "dev"
Requires-Dist: hypothesis>=6.0.0; extra == "dev"
Requires-Dist: ruff>=0.14.0; extra == "dev"
Requires-Dist: mypy>=1.8.0; extra == "dev"
Requires-Dist: pre-commit>=3.6.0; extra == "dev"
Requires-Dist: import-linter>=2.0; extra == "dev"
Requires-Dist: mkdocs>=1.5.3; extra == "dev"
Requires-Dist: mkdocs-material>=9.5.0; extra == "dev"
Requires-Dist: mkdocs-git-revision-date-localized-plugin>=1.2.0; extra == "dev"
Requires-Dist: mkdocs-minify-plugin>=0.8.0; extra == "dev"
Requires-Dist: types-pyyaml>=6.0.12; extra == "dev"
Requires-Dist: types-cachetools>=5.3.0; extra == "dev"
Requires-Dist: types-requests>=2.31.0; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=7.4.4; extra == "test"
Requires-Dist: pytest-asyncio>=0.23.3; extra == "test"
Requires-Dist: pytest-cov>=4.1.0; extra == "test"
Requires-Dist: pytest-mock>=3.12.0; extra == "test"
Requires-Dist: pytest-benchmark>=4.0.0; extra == "test"
Requires-Dist: pytest-xdist>=3.5.0; extra == "test"
Requires-Dist: pytest-alembic>=0.11.0; extra == "test"
Requires-Dist: freezegun>=1.4.0; extra == "test"
Requires-Dist: hypothesis>=6.0.0; extra == "test"
Requires-Dist: pydantic-monty>=0.0.4; extra == "test"
Provides-Extra: fuse
Requires-Dist: fusepy>=3.0.1; extra == "fuse"
Provides-Extra: postgres
Requires-Dist: psycopg2-binary>=2.9.9; extra == "postgres"
Provides-Extra: cloud-sql
Requires-Dist: cloud-sql-python-connector[asyncpg]>=1.14.0; extra == "cloud-sql"
Provides-Extra: semantic-search
Requires-Dist: txtai[database,graph]>=9.0; (sys_platform != "darwin" or platform_machine != "x86_64") and extra == "semantic-search"
Requires-Dist: faiss-cpu>=1.11.0; (platform_machine == "x86_64" or platform_machine == "aarch64" or platform_machine == "arm64") and extra == "semantic-search"
Requires-Dist: sqlite-vec>=0.1.0; extra == "semantic-search"
Requires-Dist: pgvector>=0.3.0; extra == "semantic-search"
Provides-Extra: semantic-search-remote
Requires-Dist: openai>=1.0.0; extra == "semantic-search-remote"
Provides-Extra: e2b
Requires-Dist: e2b-code-interpreter>=1.0.0; extra == "e2b"
Provides-Extra: docker
Requires-Dist: docker>=7.0.0; extra == "docker"
Provides-Extra: kafka
Requires-Dist: aiokafka>=0.11.0; extra == "kafka"
Provides-Extra: nats-export
Requires-Dist: nats-py>=2.9.0; extra == "nats-export"
Provides-Extra: pubsub
Requires-Dist: gcloud-aio-pubsub>=6.0.0; extra == "pubsub"
Provides-Extra: sse
Requires-Dist: sse-starlette>=2.2.0; extra == "sse"
Provides-Extra: event-streaming
Requires-Dist: aiokafka>=0.11.0; extra == "event-streaming"
Requires-Dist: nats-py>=2.9.0; extra == "event-streaming"
Requires-Dist: gcloud-aio-pubsub>=6.0.0; extra == "event-streaming"
Requires-Dist: sse-starlette>=2.2.0; extra == "event-streaming"
Provides-Extra: all
Requires-Dist: txtai[database,graph]>=9.0; (sys_platform != "darwin" or platform_machine != "x86_64") and extra == "all"
Requires-Dist: faiss-cpu>=1.11.0; (platform_machine == "x86_64" or platform_machine == "aarch64" or platform_machine == "arm64") and extra == "all"
Requires-Dist: psycopg2-binary>=2.9.9; extra == "all"
Requires-Dist: sqlite-vec>=0.1.0; extra == "all"
Requires-Dist: pgvector>=0.3.0; extra == "all"
Requires-Dist: openai>=1.0.0; extra == "all"
Requires-Dist: e2b-code-interpreter>=1.0.0; 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>

### The filesystem & context plane for AI agents

Give every agent one place to read, write, search, remember, and collaborate — from a single-file script to a fleet of thousands.

[![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/)
[![Python 3.12+](https://img.shields.io/badge/python-3.12+-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/) · [Roadmap](https://github.com/nexi-lab/nexus/issues)

</div>

---

## Why Nexus

Every agent framework gives you tool calling. None gives you a shared filesystem. Without one, agents duplicate files, lose context between runs, step on each other's writes, and can't discover what's already been built.

Nexus fixes this. One VFS-style interface — start embedded in a single Python process, scale to a daemon-backed deployment with auth, permissions, federation, and multi-tenant isolation. No code changes.

## How it works

```
┌─────────────────────────────────────────────────────────────────────────┐
│  BRICKS (runtime-loadable)                                              │
│  ReBAC · Auth · Agents · Delegation · Search · Memory · Governance      │
│  Workflows · Pay · MCP · Snapshots · Catalog · Identity · 25+ more      │
└─────────────────────────────────────────────────────────────────────────┘
                              ↓ protocol interface
┌─────────────────────────────────────────────────────────────────────────┐
│  KERNEL                                                                 │
│  VFS · Metastore · ObjectStore · Syscall dispatch · Pipes ·             │
│  Lock manager · Three-phase write (LSM hooks) · CAS dedup              │
└─────────────────────────────────────────────────────────────────────────┘
                              ↓ dependency injection
┌─────────────────────────────────────────────────────────────────────────┐
│  DRIVERS                                                                │
│  redb · PostgreSQL (pgvector) · S3 · GCS · Dragonfly · Zoekt · gRPC    │
└─────────────────────────────────────────────────────────────────────────┘
```

**Kernel** never changes. **Drivers** swap at config time. **Bricks** mount and unmount at runtime — 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 + Zoekt
```

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 versions history /hello.txt
```

### Terminal UI

The TUI is a separate TypeScript package built on OpenTUI:

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

File explorer, API inspector, monitoring dashboard, agent lifecycle management, and more — all from your terminal.

## 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** | Keyword + semantic + hybrid, powered by Zoekt + pgvector | Find anything by content or meaning |
| **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** | Inbox-based inter-agent messaging via pipes | Agents talk to each other without polling |
| **Federation** | Multi-zone Raft consensus with mTLS TOFU | Span data centers without a central coordinator |

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

**Bricks (runtime-loadable):** Access Manifests · Auth (API key, OAuth, mTLS) · Catalog (schema extraction) · Context Manifests · Delegation · Discovery · Identity (DID + credentials) · IPC (pipes) · MCP · Mount · Parsers (50+ formats via MarkItDown) · Pay · Portability (import/export) · ReBAC · Sandbox (Docker) · Search · Share Links (capability URLs) · Snapshots · Task Manager · TUS Uploads (resumable) · Versioning · Workflows · Workspace

**System services:** Agent Registry · Agent Runtime · Event Bus · Event Log · Namespace · Scheduler (fair-share, priority tiers) · Sync · Lifecycle

</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 + Zoekt | 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

# 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

# Pin to a specific version
nexus init --preset shared --image-tag 0.9.4

# Stack lifecycle
nexus down                                    # stop all services
nexus logs                                    # tail logs
nexus restart                                 # down + up
nexus upgrade                                 # pull latest image for your channel
```

### 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.

## 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`
For Rust extensions: `maturin develop --release -m rust/nexus_pyo3/Cargo.toml`

See [CONTRIBUTING.md](CONTRIBUTING.md) for the full 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>

<details>
<summary><code>maturin develop</code> fails at the repo root</summary>

Point maturin at a crate manifest: `maturin develop --release -m rust/nexus_pyo3/Cargo.toml`

</details>

<details>
<summary><code>faiss-cpu</code> resolution fails</summary>

Only install semantic search extras on platforms with compatible `txtai`/`faiss-cpu` wheels: `pip install "nexus-ai-fs[semantic-search]"`

</details>

## License

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

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