Metadata-Version: 2.4
Name: mirage-ai
Version: 0.0.3a0
Summary: A unified virtual filesystem for AI agents. Mount S3, Google Drive, Slack, Gmail, GitHub, Linear, Notion, Postgres, MongoDB, SSH, and more behind one filesystem so agents read, write, and pipe across services with familiar shell commands.
Author-email: Zecheng Zhang <zecheng@strukto.ai>
License-Expression: Apache-2.0
Project-URL: Homepage, https://www.strukto.ai/
Project-URL: Repository, https://github.com/strukto-ai/mirage
Project-URL: Documentation, https://docs.mirage.strukto.ai
Project-URL: Issues, https://github.com/strukto-ai/mirage/issues
Keywords: ai-agents,filesystem,vfs,fuse,s3,google-drive,slack,agent-tools,shell,rag
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Filesystems
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiofiles>=24.1.0
Requires-Dist: aiohttp>=3.13.3
Requires-Dist: fastapi>=0.135.1
Requires-Dist: httpx>=0.28.1
Requires-Dist: python-multipart>=0.0.27
Requires-Dist: orjson>=3.11
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: tree-sitter>=0.25.2
Requires-Dist: tree-sitter-bash>=0.25.1
Requires-Dist: typer>=0.12.0
Requires-Dist: uvicorn[standard]>=0.41.0
Requires-Dist: jq>=1.11.0
Requires-Dist: pyjwt[crypto]>=2.10
Requires-Dist: dulwich>=1.2.5
Provides-Extra: s3
Requires-Dist: aioboto3>=13.0; extra == "s3"
Provides-Extra: r2
Requires-Dist: aioboto3>=13.0; extra == "r2"
Provides-Extra: gcs
Requires-Dist: aioboto3>=13.0; extra == "gcs"
Provides-Extra: oci
Requires-Dist: aioboto3>=13.0; extra == "oci"
Provides-Extra: databricks
Requires-Dist: databricks-sdk>=0.72.0; extra == "databricks"
Provides-Extra: ssh
Requires-Dist: asyncssh>=2.23.0; extra == "ssh"
Provides-Extra: nextcloud
Requires-Dist: opendal>=0.47.1; extra == "nextcloud"
Provides-Extra: hf
Requires-Dist: opendal>=0.47.1; extra == "hf"
Provides-Extra: fuse
Requires-Dist: mfusepy>=1.0.0; extra == "fuse"
Provides-Extra: mongodb
Requires-Dist: motor>=3.7.1; extra == "mongodb"
Provides-Extra: postgres
Requires-Dist: asyncpg>=0.30.0; extra == "postgres"
Provides-Extra: redis
Requires-Dist: redis[hiredis]>=5.0; extra == "redis"
Provides-Extra: email
Requires-Dist: aioimaplib>=2.0.1; extra == "email"
Requires-Dist: aiosmtplib>=5.1.0; extra == "email"
Provides-Extra: parquet
Requires-Dist: pandas>=3.0.1; extra == "parquet"
Requires-Dist: pyarrow>=15.0; extra == "parquet"
Provides-Extra: hdf5
Requires-Dist: h5py>=3.16.0; extra == "hdf5"
Requires-Dist: tables>=3.11.1; extra == "hdf5"
Requires-Dist: pandas>=3.0.1; extra == "hdf5"
Provides-Extra: pdf
Requires-Dist: pypdfium2>=5.7.0; extra == "pdf"
Requires-Dist: pillow>=12.2.0; extra == "pdf"
Provides-Extra: langfuse
Requires-Dist: langfuse>=4.2.0; extra == "langfuse"
Provides-Extra: chroma
Requires-Dist: chromadb-client>=1.0.0; extra == "chroma"
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.88; extra == "anthropic"
Provides-Extra: openai
Requires-Dist: openai>=2.30.0; extra == "openai"
Requires-Dist: openai-agents>=0.14.7; extra == "openai"
Provides-Extra: pydantic-ai
Requires-Dist: pydantic-ai-slim>=1.56; extra == "pydantic-ai"
Requires-Dist: pydantic-ai-backend>=0.1.0; extra == "pydantic-ai"
Requires-Dist: mirage-ai[pdf]; extra == "pydantic-ai"
Provides-Extra: deepagents
Requires-Dist: deepagents>=0.4.12; extra == "deepagents"
Requires-Dist: mirage-ai[pdf]; extra == "deepagents"
Provides-Extra: openhands
Requires-Dist: openhands-sdk>=1.18.0; python_version >= "3.12" and extra == "openhands"
Requires-Dist: openhands-tools>=1.18.0; python_version >= "3.12" and extra == "openhands"
Provides-Extra: agno
Requires-Dist: agno>=2.4.0; extra == "agno"
Provides-Extra: camel
Requires-Dist: camel-ai<0.3,>=0.2.40; extra == "camel"
Requires-Dist: markitdown>=0.1.5; extra == "camel"
Provides-Extra: daytona
Requires-Dist: daytona>=0.176.0; extra == "daytona"
Provides-Extra: all
Requires-Dist: mirage-ai[s3]; extra == "all"
Requires-Dist: mirage-ai[r2]; extra == "all"
Requires-Dist: mirage-ai[gcs]; extra == "all"
Requires-Dist: mirage-ai[oci]; extra == "all"
Requires-Dist: mirage-ai[databricks]; extra == "all"
Requires-Dist: mirage-ai[ssh]; extra == "all"
Requires-Dist: mirage-ai[nextcloud]; extra == "all"
Requires-Dist: mirage-ai[hf]; extra == "all"
Requires-Dist: mirage-ai[fuse]; extra == "all"
Requires-Dist: mirage-ai[mongodb]; extra == "all"
Requires-Dist: mirage-ai[postgres]; extra == "all"
Requires-Dist: mirage-ai[redis]; extra == "all"
Requires-Dist: mirage-ai[email]; extra == "all"
Requires-Dist: mirage-ai[parquet]; extra == "all"
Requires-Dist: mirage-ai[hdf5]; extra == "all"
Requires-Dist: mirage-ai[pdf]; extra == "all"
Requires-Dist: mirage-ai[langfuse]; extra == "all"
Requires-Dist: mirage-ai[chroma]; extra == "all"
Requires-Dist: mirage-ai[anthropic]; extra == "all"
Requires-Dist: mirage-ai[openai]; extra == "all"
Requires-Dist: mirage-ai[pydantic-ai]; extra == "all"
Requires-Dist: mirage-ai[deepagents]; extra == "all"
Requires-Dist: mirage-ai[openhands]; extra == "all"
Requires-Dist: mirage-ai[agno]; extra == "all"
Requires-Dist: mirage-ai[daytona]; extra == "all"
Provides-Extra: lancedb
Requires-Dist: lancedb>=0.33.0; extra == "lancedb"
Dynamic: license-file

<p align="center">
  <img src="https://raw.githubusercontent.com/strukto-ai/mirage/main/assets/mirage-og-light@2x.png" alt="Mirage: A Unified Virtual File System for AI Agents" width="900">
</p>

<p align="center">
    <a href="https://docs.mirage.strukto.ai" alt="Documentation">
        <img src="https://img.shields.io/badge/mirage-docs-0C0C0C?labelColor=FAFAFA" /></a>
    <a href="https://www.strukto.ai" alt="Website">
        <img src="https://img.shields.io/badge/made by-strukto.ai-0C0C0C?labelColor=FAFAFA" /></a>
    <a href="https://github.com/strukto-ai/mirage/blob/main/LICENSE" alt="License">
        <img src="https://img.shields.io/github/license/strukto-ai/mirage?color=0C0C0C&labelColor=FAFAFA" /></a>
    <a href="https://discord.gg/u8BPQ65KsS" alt="Discord">
        <img src="https://img.shields.io/badge/discord-join-0C0C0C?labelColor=FAFAFA&logo=discord&logoColor=0C0C0C" /></a>
    <br/>
    <a href="https://docs.mirage.strukto.ai/python/quickstart" alt="Python docs">
        <img src="https://img.shields.io/badge/python-docs-0C0C0C?labelColor=FAFAFA&logo=python&logoColor=0C0C0C" alt="Python docs"></a>
    <a href="https://pypi.org/project/mirage-ai/" alt="PyPI Version">
        <img src="https://img.shields.io/pypi/v/mirage-ai.svg?color=0C0C0C&labelColor=FAFAFA"/></a>
    <br/>
    <a href="https://docs.mirage.strukto.ai/typescript/quickstart" alt="TypeScript docs">
        <img src="https://img.shields.io/badge/typescript-docs-0C0C0C?labelColor=FAFAFA&logo=typescript&logoColor=0C0C0C" alt="TypeScript docs"></a>
    <a href="https://www.npmjs.com/package/@struktoai/mirage-node" alt="NPM Version">
        <img src="https://img.shields.io/npm/v/@struktoai/mirage-node.svg?color=0C0C0C&labelColor=FAFAFA"/></a>
</p>

<p align="center">
  <a href="https://github.com/strukto-ai/mirage#readme"><img alt="README in English" src="https://img.shields.io/badge/English-d9d9d9"></a>
  <a href="https://github.com/strukto-ai/mirage/blob/main/readme/README.zh-CN.md"><img alt="简体中文 README" src="https://img.shields.io/badge/简体中文-d9d9d9"></a>
  <a href="https://github.com/strukto-ai/mirage/blob/main/readme/README.zh-TW.md"><img alt="繁體中文 README" src="https://img.shields.io/badge/繁體中文-d9d9d9"></a>
  <a href="https://github.com/strukto-ai/mirage/blob/main/readme/README.fr.md"><img alt="README en Français" src="https://img.shields.io/badge/Français-d9d9d9"></a>
  <a href="https://github.com/strukto-ai/mirage/blob/main/readme/README.vi.md"><img alt="README Tiếng Việt" src="https://img.shields.io/badge/Ti%E1%BA%BFng%20Vi%E1%BB%87t-d9d9d9"></a>
  <a href="https://github.com/strukto-ai/mirage/blob/main/readme/README.ko.md"><img alt="README 한국어" src="https://img.shields.io/badge/%ED%95%9C%EA%B5%AD%EC%96%B4-d9d9d9"></a>
</p>

Mirage is **a Unified Virtual File System for AI Agents**: it mounts services and data sources like S3, Google Drive, Slack, Gmail, and Redis side-by-side as one filesystem. Any LLM that already knows bash can read, grep, and pipe across every backend out of the box, with zero new vocabulary.

```ts
const ws = new Workspace({
  '/data':  new RAMResource(),
  '/s3':    new S3Resource({ bucket: 'logs' }),
  '/slack': new SlackResource({ token: process.env.SLACK_BOT_TOKEN! }),
})

await ws.execute('grep -r alert /slack/channels/general__C04QX/ | wc -l')
await ws.execute('cp /s3/report.csv /data/local.csv')
await ws.execute('wc -l $(find /s3/data -name "*.jsonl")')

// Commands are extensible: register new commands, or override one per
// resource + filetype, e.g. `cat` on S3 Parquet renders rows as JSON.
ws.command('summarize', ...)
ws.command('cat', { resource: 's3', filetype: 'parquet' }, ...)

await ws.execute('summarize /data/local.csv')
await ws.execute('cat /s3/events/2026-05-06.parquet | jq .user')
```

## About

- **One interface instead of N SDKs and M MCPs.** Every service speaks the same filesystem semantics, and pipelines compose across services as naturally as on a local disk.
- **Around 50 built-in backends:** RAM, Disk, Redis, S3 / R2 / OCI / Supabase / GCS, Gmail / GDrive / GDocs / GSheets / GSlides, GitHub / Linear / Notion / Trello, Slack / Discord / Telegram / Email, MongoDB / Postgres / LanceDB, SSH, and more, mounted side-by-side under a single root.
- **Portable workspaces:** clone, snapshot, and version a workspace; agent runs move between machines without restarting or reconfiguring the system.
- **Embeddable:** the Python and TypeScript SDKs run in-process inside FastAPI, Express, browser apps, or any async runtime; no separate process required.
- **Agent integrations:** OpenAI Agents SDK, Vercel AI SDK, LangChain, Pydantic AI, CAMEL, and OpenHands via the SDKs; coding agents like Claude Code and Codex via the lightweight CLI + daemon.

## Architecture

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/strukto-ai/mirage/main/assets/mirage-arch-dark.svg">
    <img src="https://raw.githubusercontent.com/strukto-ai/mirage/main/assets/mirage-arch-light.svg" alt="Mirage architecture: AI Agent and Application → Mirage Bash and VFS → Dispatcher &amp; Cache → Infrastructure and Remote" width="720">
  </picture>
</p>

## Installation

- **Python** ≥ 3.11 for the `mirage-ai` package and the `mirage` CLI
- **Node.js** ≥ 20 for the TypeScript SDK
- **macOS** or **Linux** (FUSE-based mounts require platform support)

### Python

```bash
uv add mirage-ai    # installs the `mirage` library and the `mirage` CLI binary
```

### TypeScript

```bash
npm install @struktoai/mirage-node      # Node.js servers and CLIs
npm install @struktoai/mirage-browser   # browser / edge runtimes
npm install @struktoai/mirage-agents    # OpenAI / Vercel AI / LangChain / Mastra adapters
```

Both runtime packages pull in `@struktoai/mirage-core` automatically.

### CLI

```bash
curl -fsSL https://strukto.ai/mirage/install.sh | sh
# or
npm install -g @struktoai/mirage-cli
# or
uvx mirage-ai
# or
npx @struktoai/mirage-cli
```

## Quickstart

### Python

```python
from mirage import Workspace
from mirage.resource.ram import RAMResource
from mirage.resource.s3 import S3Config, S3Resource

ws = Workspace({
    "/data": RAMResource(),
    "/s3":   S3Resource(S3Config(bucket="my-bucket")),
})

await ws.execute("cp /s3/report.csv /data/report.csv")
await ws.execute("grep alert /s3/data/log.jsonl | wc -l")

await ws.snapshot("demo.tar")
```

### TypeScript

```ts
import { Workspace, RAMResource, S3Resource } from '@struktoai/mirage-node'

const ws = new Workspace({
  '/data': new RAMResource(),
  '/s3':   new S3Resource({ bucket: 'my-bucket' }),
})

await ws.execute('cp /s3/report.csv /data/report.csv')
await ws.execute('grep alert /s3/data/log.jsonl | wc -l')

await ws.snapshot('demo.tar')
```

### CLI

```bash
mirage workspace create ws.yaml --id demo
mirage execute   --workspace_id demo --command "cp /s3/report.csv /data/report.csv"
mirage provision --workspace_id demo --command "cat /s3/data/large.jsonl"
mirage workspace snapshot demo demo.tar
mirage workspace load demo.tar --id demo-restored
```

## Agent Frameworks

Mirage plugs into agent frameworks as a sandbox or tool layer. POSIX operations such as `read` can also be customized per resource and filetype, e.g. reading a PDF returns parsed pages instead of raw bytes.

|               | Integrations                                                                                                                                                                                                                                                                                                                                                                                                               |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Python        | [OpenAI Agents SDK](https://docs.mirage.strukto.ai/python/agents/openai-agents), [LangChain](https://docs.mirage.strukto.ai/python/agents/langchain), [Pydantic AI](https://docs.mirage.strukto.ai/python/agents/pydantic-ai), [CAMEL](https://docs.mirage.strukto.ai/python/agents/camel), [OpenHands](https://docs.mirage.strukto.ai/python/agents/openhands), [Agno](https://docs.mirage.strukto.ai/python/agents/agno) |
| TypeScript    | [Vercel AI SDK](https://docs.mirage.strukto.ai/typescript/agents/vercel), [OpenAI Agents SDK](https://docs.mirage.strukto.ai/typescript/agents/openai), [LangChain](https://docs.mirage.strukto.ai/typescript/agents/langchain), [Mastra](https://docs.mirage.strukto.ai/typescript/agents/mastra)                                                                                                                         |
| Coding agents | [Claude Code](https://docs.mirage.strukto.ai/python/agents/claude-code), [Codex](https://docs.mirage.strukto.ai/python/agents/codex), [OpenCode](https://docs.mirage.strukto.ai/typescript/agents/opencode), [Pi](https://docs.mirage.strukto.ai/typescript/agents/pi)                                                                                                                                                     |

## Cache

Every `Workspace` has a two-layer cache so repeated work against remote backends hits local state instead of the network:

- **Index cache:** listings and metadata. The first directory walk hits the API; later ones serve from the index until the TTL expires (default 10 minutes).
- **File cache:** object bytes. The first read streams from origin; later pipelines read from cache (default 512 MB).

Both layers default to in-process RAM with zero setup. A Redis store shares cache state across workers, processes, and machines:

```ts
import { RedisFileCacheStore, S3Resource, Workspace } from '@struktoai/mirage-node'

const ws = new Workspace(
  { '/s3': new S3Resource({ bucket: 'my-bucket' }) },
  {
    cache: new RedisFileCacheStore({ url: 'redis://localhost:6379/0', cacheLimit: '8GB' }),
    index: { type: 'redis', url: 'redis://localhost:6379/0', ttl: 600 },
  },
)
```

See the [cache docs](https://docs.mirage.strukto.ai/home/cache) for the full miss/hit lifecycle.
