Metadata-Version: 2.4
Name: nexus-ai-fs
Version: 0.9.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.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: litellm>=1.8.10
Requires-Dist: tiktoken>=0.12
Requires-Dist: anthropic>=0.75
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"
Requires-Dist: langchain-core>=0.3.0; extra == "test"
Requires-Dist: langgraph>=0.2.0; 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">
  <img src="assets/logo.png" alt="Nexus Logo" width="200"/>

  # Nexus

  [![Test](https://github.com/nexi-lab/nexus/actions/workflows/test.yml/badge.svg)](https://github.com/nexi-lab/nexus/actions/workflows/test.yml)
  [![Lint](https://github.com/nexi-lab/nexus/actions/workflows/lint.yml/badge.svg)](https://github.com/nexi-lab/nexus/actions/workflows/lint.yml)

  [![PyPI version](https://badge.fury.io/py/nexus-ai-fs.svg)](https://badge.fury.io/py/nexus-ai-fs)
  [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://github.com/nexi-lab/nexus/blob/main/LICENSE)
  [![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)

  [Docs](https://nexi-lab.github.io/nexus/) • [Quickstart](https://nexi-lab.github.io/nexus/getting-started/quickstart/) • [PyPI](https://pypi.org/project/nexus-ai-fs/) • [Examples](https://github.com/nexi-lab/nexus/tree/main/examples)
</div>

Nexus = filesystem/context plane.

⚠️ **Beta**: Nexus is under active development. APIs and deployment defaults may change.

## What Nexus Does

Nexus gives agents one place to read, write, search, and carry context across files, services, and runs. The core abstraction is a VFS-style interface that can start local in-process and grow into a daemon-backed deployment when you need remote access, permissions, or multi-tenant control.

## Quick Start

This is the verified source-checkout path as of March 11, 2026. It uses `uv`,
Python 3.14, the lightweight `requirements-minimal.txt` set, and does not
require a Rust build.

```bash
uv venv --python 3.14
source .venv/bin/activate
uv pip install -r requirements-minimal.txt
uv pip install -e . --no-deps

python - <<'PY'
from nexus.sdk import connect

nx = connect(
    config={
        "profile": "minimal",
        "data_dir": "./nexus-data",
    }
)

nx.sys_write("/hello.txt", b"Hello, Nexus!")
print(nx.sys_read("/hello.txt").decode())

nx.close()
PY
```

Expected output:

```text
Hello, Nexus!
```

The commands below assume the same activated `.venv`.

Local CLI path from a source checkout:

```bash
python -m nexus.cli.main init .nexus-cli-demo
export NEXUS_DATA_DIR="$PWD/.nexus-cli-demo/nexus-data"

python -m nexus.cli.main write /workspace/hello.txt "hello from cli"
python -m nexus.cli.main cat /workspace/hello.txt
python -m nexus.cli.main ls /workspace
```

If you installed from PyPI, use `nexus` instead of `python -m nexus.cli.main`.

## Optional Capabilities

- Full dev/test environment: `uv sync --extra dev --extra test`
- txtai/FAISS semantic search stack: `uv sync --extra semantic-search`
- Optional Rust BLAKE3 acceleration: `maturin develop --release -m rust/nexus_pyo3/Cargo.toml`
- Rust metastore / federation extensions: `maturin develop --release -m rust/nexus_raft/Cargo.toml --features python` or `--features full`

## Troubleshooting

- `ModuleNotFoundError: No module named 'nexus'`: you are in a source checkout without installing the package into the active interpreter. Use the `uv` setup above or install `nexus-ai-fs` from PyPI.
- `maturin develop --release` fails at the repo root: the root [Cargo.toml](./Cargo.toml) is a workspace manifest. Point `maturin` at a crate manifest under `rust/`.
- `Rust BLAKE3 extension not available`: this is an optional performance path. The default quickstart uses the Python `blake3` package.
- `faiss-cpu` resolution fails: stay on the default source quickstart above, or opt into `semantic-search` only on a platform with compatible `txtai`/`faiss-cpu` wheels.

For the full walkthrough, see the [quickstart page](https://nexi-lab.github.io/nexus/getting-started/quickstart/).

## Three Landing Paths

- **Local SDK**: Start local, keep the filesystem/context plane inside your process, and integrate from Python. Docs: [Local SDK path](https://nexi-lab.github.io/nexus/paths/embedded-sdk/)
- **Shared daemon**: Run `nexusd` when you need a long-lived service, remote clients, or operational controls. Docs: [Shared daemon path](https://nexi-lab.github.io/nexus/paths/daemon-and-remote/)
- **Architecture**: Read the kernel, storage, and proposal docs before changing the system model. Docs: [Architecture path](https://nexi-lab.github.io/nexus/paths/architecture/)

## Trust Boundaries

- The quickstart above is a local path. It is intentionally smaller than a production deployment.
- Remote SDK access uses the `remote` profile and depends on a running `nexusd` plus a configured gRPC port.
- Permissions, memory, and federation are deployment capabilities, not implied by the basic local write/read example.

## Architecture

```
┌──────────────────────────────────────────────────────────────┐
│  SERVICES (user space)                                       │
│  Loadable at runtime. ReBAC, Auth, Agents, Search, Skills…   │
└──────────────────────────────────────────────────────────────┘
                          ↓ protocol interface
┌──────────────────────────────────────────────────────────────┐
│  KERNEL                                                      │
│  VFS, MetastoreABC, ObjectStoreABC, syscall dispatch,        │
│  pipes, lock manager, three-phase dispatch (LSM hooks)       │
└──────────────────────────────────────────────────────────────┘
                          ↓ dependency injection
┌──────────────────────────────────────────────────────────────┐
│  DRIVERS                                                     │
│  redb, S3, PostgreSQL, Dragonfly, LocalDisk, gRPC…           │
└──────────────────────────────────────────────────────────────┘
```

| Tier | Linux Analogue | Nexus | Swap time |
|------|---------------|-------|-----------|
| **Kernel** | vmlinuz (scheduler, mm, VFS) | VFS, MetastoreABC, syscall dispatch | Never |
| **Drivers** | Compiled-in drivers (`=y`) | redb, S3, PostgreSQL, SearchBrick | Config-time (DI) |
| **Services** | Loadable kernel modules (`insmod`/`rmmod`) | 23 protocols — ReBAC, Mount, Auth, Agents, … | Runtime |

**Invariant:** Services depend on kernel interfaces, never the reverse. The kernel operates with zero services loaded.

### Four Storage Pillars

Storage is abstracted by **capability** (access pattern + consistency guarantee), not by domain:

| Pillar | ABC | Capability | Kernel role |
|--------|-----|------------|-------------|
| **Metastore** | `MetastoreABC` | Ordered KV, CAS, prefix scan, optional Raft SC | Required — sole kernel init param |
| **ObjectStore** | `ObjectStoreABC` | Streaming blob I/O, petabyte scale | Interface only — mounted dynamically |
| **RecordStore** | `RecordStoreABC` | Relational ACID, JOINs, vector search | Services only — optional |
| **CacheStore** | `CacheStoreABC` | Ephemeral KV, Pub/Sub, TTL | Optional — defaults to `NullCacheStore` |

### Deployment Profiles (Distros)

Same kernel, different service sets — like Linux distros:

| Profile | Linux Analogue | Target | Services |
|---------|---------------|--------|----------|
| **minimal** | initramfs | Bare minimum | 1 |
| **embedded** | BusyBox | MCU, WASM (<1 MB) | 2 |
| **lite** | Alpine | Pi, Jetson, mobile | 8 |
| **full** | Ubuntu Desktop | Desktop, laptop | 21 |
| **cloud** | Ubuntu Server | k8s, serverless | 22 (all) |
| **remote** | NFS client | Client-side proxy | 0 |

See [Kernel Architecture](https://nexi-lab.github.io/nexus/architecture/kernel-architecture/) for the full design.

## Examples

| Framework | Description | Location |
|-----------|-------------|----------|
| CrewAI | Multi-agent collaboration | [examples/crewai/](https://github.com/nexi-lab/nexus/tree/main/examples/crewai) |
| LangGraph | Permission-based workflows | [examples/langgraph_integration/](https://github.com/nexi-lab/nexus/tree/main/examples/langgraph_integration) |
| Claude SDK | ReAct agent pattern | [examples/claude_agent_sdk/](https://github.com/nexi-lab/nexus/tree/main/examples/claude_agent_sdk) |
| OpenAI Agents | Multi-tenant with memory | [examples/openai_agents/](https://github.com/nexi-lab/nexus/tree/main/examples/openai_agents) |
| Google ADK | Agent Development Kit | [examples/google_adk/](https://github.com/nexi-lab/nexus/tree/main/examples/google_adk) |
| CLI | 40+ shell demos | [examples/cli/](https://github.com/nexi-lab/nexus/tree/main/examples/cli) |

## 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/
```

If you are working on the txtai search stack, add `--extra semantic-search`.

## License

© 2026 Nexi Labs, Inc. Licensed under Apache License 2.0 — see [LICENSE](https://github.com/nexi-lab/nexus/blob/main/LICENSE) for details.
