Metadata-Version: 2.4
Name: maivn-studio
Version: 0.4.0
Summary: Local developer studio for discovering, running, and debugging mAIvn SDK apps
Project-URL: Homepage, https://maivn.io
Project-URL: Repository, https://github.com/mAIvn-developer/maivn-studio
Project-URL: Issues, https://github.com/mAIvn-developer/maivn-studio/issues
Project-URL: Changelog, https://github.com/mAIvn-developer/maivn-studio/blob/master/CHANGELOG.md
Author-email: Chad Heathcote <developer@maivn.io>
License-Expression: LicenseRef-BSL-1.1
License-File: LICENSE
Keywords: agents,ai,developer-tool,fastapi,maivn,studio
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: fastapi>=0.136.1
Requires-Dist: maivn-shared<0.5.0,>=0.4.0
Requires-Dist: maivn<0.5.0,>=0.4.0
Requires-Dist: pydantic>=2.13.3
Requires-Dist: sse-starlette>=2.1.3
Requires-Dist: uvicorn[standard]>=0.46.0
Description-Content-Type: text/markdown

# mAIvn Studio

Local developer studio for discovering demos, running sessions, and debugging agent workflows.

## Key Capabilities

- Demo discovery from configured repository paths
- Rich demo introspection (agents, swarms, tools, prompts, private data schema)
- Multi-turn session APIs
- Batch Matrix and async-batch session execution with grouped result cards
- Real-time Server-Sent Events stream for execution visibility
- Runtime patching for demos, agents, and swarms

## Quick Start

For end users or SDK consumers:

```bash
pip install "maivn[studio]"
maivn studio
```

Run `maivn studio` from the directory that contains your `maivn_studio.json`
file. Studio discovers that config from the current working directory and then
walks up parent directories.

You can also launch the companion package directly:

```bash
maivn-studio
```

For monorepo development:

```bash
uv sync
cd apps/maivn-demos
uv run maivn studio
```

If you need to run the Studio package directly:

```bash
cd apps/maivn-studio
uv run -m maivn_studio
```

If you launch Studio without a config file, the default URL is
`http://127.0.0.1:8080`. The shared demos config at
`apps/maivn-demos/maivn_studio.json` uses `http://127.0.0.1:8088`.

## Documentation

- `docs/getting-started.md`
- `docs/authoring-and-debugging.md`
- `../../libraries/maivn/docs/guides/maivn-studio.md`
- `../../libraries/maivn/docs/api/events.md`
- `../../libraries/maivn/docs/guides/frontend-events.md`

Studio's backend event stream is built on the shared `maivn.events.EventBridge` contract. Known mAIvn event families are standardized in the shared bridge layer, so Studio inherits canonical packet shapes and stable tool/assignment/scope identities from the SDK. Replay ownership is explicit in the session execution path, Studio keeps any legacy/raw frontend compatibility parsing at the SSE ingress boundary, and the remaining app-specific dedupe is limited to overlapping logical deliveries such as repeated interrupts or repeated identical status messages within a turn.

## Configuration

Studio reads `maivn_studio.json` (if present) for:

- host/port
- demo discovery paths
- explicit demo definitions and variants

## Developer Commands

```bash
# From apps/maivn-studio

# Backend tests
uv run pytest tests/

# Backend checks
uv run pyright
uv run ruff check .
uv build --wheel
python scripts/check_wheel_contents.py dist/*.whl

# Frontend tests and checks
cd frontend
npm ci
npm run test
npm run check
npm run lint
npm run build
npm run format:check
```
