Metadata-Version: 2.4
Name: zvec-studio
Version: 0.1.10
Summary: Open-source visual management tool for Zvec embedded vector database
Author: Zvec Studio Contributors
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/zvec/zvec-studio
Project-URL: Repository, https://github.com/zvec/zvec-studio
Project-URL: Issues, https://github.com/zvec/zvec-studio/issues
Keywords: zvec,vector-database,visualization,studio
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Database
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi<0.120,>=0.115
Requires-Dist: uvicorn[standard]<0.35,>=0.30
Requires-Dist: pydantic<3.0,>=2.7
Requires-Dist: pydantic-settings<3.0,>=2.4
Requires-Dist: python-ulid<4.0,>=3.0
Requires-Dist: orjson<4.0,>=3.10
Requires-Dist: typing-extensions>=4.12
Requires-Dist: zvec<0.5,>=0.4
Requires-Dist: numpy>=1.23
Provides-Extra: ai
Requires-Dist: sentence-transformers<6.0,>=5.0; extra == "ai"
Requires-Dist: dashtext>=0.0.7; extra == "ai"
Requires-Dist: dashscope>=1.20; extra == "ai"
Requires-Dist: openai>=1.40; extra == "ai"
Provides-Extra: dev
Requires-Dist: pytest<9.0,>=8.3; extra == "dev"
Requires-Dist: pytest-asyncio<0.25,>=0.24; extra == "dev"
Requires-Dist: pytest-cov<6.0,>=5.0; extra == "dev"
Requires-Dist: pytest-benchmark<5.0,>=4.0; extra == "dev"
Requires-Dist: httpx<0.29,>=0.27; extra == "dev"
Requires-Dist: hypothesis<7.0,>=6.112; extra == "dev"
Requires-Dist: schemathesis<4.0,>=3.36; extra == "dev"
Requires-Dist: ruff<0.9,>=0.6; extra == "dev"
Requires-Dist: mypy<2.0,>=1.11; extra == "dev"
Requires-Dist: types-setuptools; extra == "dev"
Provides-Extra: packaging
Requires-Dist: pyinstaller<7.0,>=6.10; extra == "packaging"
Dynamic: license-file

<p align="right">
  English | <a href="https://github.com/zvec-ai/zvec-studio/blob/main/README.zh-CN.md">中文</a>
</p>

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/zvec-ai/zvec-studio/main/docs/assets/hero-dark.svg" />
    <img src="https://raw.githubusercontent.com/zvec-ai/zvec-studio/main/docs/assets/hero-light.svg" width="480" alt="Zvec Studio" />
  </picture>
</p>

<p align="center">
  <strong>Visual management tool for the <a href="https://github.com/alibaba/zvec">Zvec</a> embedded vector database</strong><br/>
  Browse data, test queries, and manage schemas — without writing code.
</p>

<p align="center">
  <a href="https://github.com/zvec-ai/zvec-studio/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue.svg" alt="License"/></a>
  <a href="https://pypi.org/project/zvec-studio/"><img src="https://img.shields.io/pypi/v/zvec-studio?color=blue&label=version" alt="Version"/></a>
  <a href="#"><img src="https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-3DDC84" alt="Platforms"/></a>
  <a href="https://github.com/zvec-ai/zvec-studio/actions/workflows/ci.yml"><img src="https://github.com/zvec-ai/zvec-studio/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI"/></a>
</p>

<p align="center">
  <img src="https://raw.githubusercontent.com/zvec-ai/zvec-studio/main/docs/assets/tour-guide.gif" width="720" alt="Zvec Studio guided tour" />
</p>

---

## 📦 Installation

### Option 1: pip (recommended for developers)

Requires Python 3.10 – 3.14.

```bash
pip install zvec-studio
zvec-studio
```

Opens http://127.0.0.1:7860 in your browser.

> **Need embedding & reranking?** Install with the `[ai]` extra to enable built-in embedding & reranking functions:
>
> ```bash
> pip install zvec-studio[ai]
> ```

### Option 2: Desktop download (experimental)

Grab the installer for your platform from [GitHub Releases](https://github.com/zvec-ai/zvec-studio/releases):

| Platform | Architectures | Installer |
|----------|---------------|-----------|
| macOS | Apple Silicon (arm64) | `.dmg` |
| Linux | x86_64, arm64 | `.deb` / `.AppImage` |
| Windows | x86_64 | `.msi` / `.exe` |

Double-click to run — no Python needed.

### Option 3: From source

```bash
git clone https://github.com/zvec-ai/zvec-studio.git
cd zvec-studio
make install    # install Node deps + backend uv environment
make dev        # starts backend + frontend dev servers
```

> **Need embedding & reranking?** `make install` does NOT install AI runtime
> dependencies (`sentence-transformers`, `dashscope`, etc.) to keep CI fast. Run
> `make install.ai` instead if you want to use built-in functions like
> `local-dense`, `bm25`, or `dashscope`.

> Prerequisites: **Node.js ≥ 20**, **pnpm ≥ 9**, **Python ≥ 3.10**, **uv**, **Rust** (desktop only).
> See [Contributing](https://github.com/zvec-ai/zvec-studio/blob/main/CONTRIBUTING.md) for the full dev setup guide.

## ⚡ Quick Start

1. **Create a collection** — Collections → Create. Define vector and scalar fields.
2. **Insert data** — Paste JSON documents in the Write tab.
3. **Vector search** — Paste a query vector in the Query tab, set TopK, hit Search.
4. **AI search** — Register an embedding model, then search by typing text directly.

Full walkthrough → [Getting Started](https://github.com/zvec-ai/zvec-studio/blob/main/docs/getting-started.md)

## 📖 Documentation

| | |
|---|---|
| [Getting Started](https://github.com/zvec-ai/zvec-studio/blob/main/docs/getting-started.md) | 10-minute walkthrough from install to first search |
| [Architecture](https://github.com/zvec-ai/zvec-studio/blob/main/docs/architecture.md) | Request flow, module map, code index |
| [API Reference](https://github.com/zvec-ai/zvec-studio/blob/main/docs/api.md) | REST endpoints, request/response formats, error codes |
| [Testing](https://github.com/zvec-ai/zvec-studio/blob/main/docs/testing.md) | Test strategy, self-verification loop, performance baselines |
| [Packaging](https://github.com/zvec-ai/zvec-studio/blob/main/docs/PACKAGING.md) | PyInstaller + Tauri cross-platform packaging |
| [Contributing](https://github.com/zvec-ai/zvec-studio/blob/main/CONTRIBUTING.md) | Dev setup, code style, commit workflow |

## 🗺️ Roadmap

| Version | Focus |
|---------|-------|
| **v0.1.x** (current) | Collection CRUD, schema evolution, document ops, vector search, AI extension, i18n, desktop app |
| **v0.2.x** | Data import/export, virtual scrolling, batch operations, advanced search |
| **v0.3.x** | Vector visualization (UMAP/t-SNE), clustering, AI Agent, SDK code generation |
| **v0.4.x** | VS Code extension, API Playground, webhooks & notifications |

## 🤝 Contributing

Contributions welcome! See [CONTRIBUTING.md](https://github.com/zvec-ai/zvec-studio/blob/main/CONTRIBUTING.md) for details.

```bash
make dev        # Start dev servers
make verify     # Lint + typecheck + tests
```

## 📄 License

[Apache License 2.0](https://github.com/zvec-ai/zvec-studio/blob/main/LICENSE)
