Metadata-Version: 2.4
Name: maivn-studio
Version: 0.4.2
Summary: Local developer studio for discovering, running, and debugging mAIvn SDK apps
Project-URL: Homepage, https://maivn.io
Project-URL: Documentation, https://developer.maivn.io/docs
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.1
Requires-Dist: maivn<0.5.0,>=0.4.1
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

## Ecosystem

`maivn-studio` is the local studio in the **mAIvn** developer ecosystem. Learn more at
[maivn.io](https://maivn.io) — or dive into the developer hub at
[developer.maivn.io](https://developer.maivn.io).

```mermaid
flowchart TD
    platform["mAIvn platform<br/>hosted agent API"]
    sdk["maivn<br/>Python SDK — agents · tools · swarms"]
    shared["maivn-shared<br/>shared contracts & models"]
    tools["maivn-tools<br/>optional connector toolsets"]
    studio["maivn-studio<br/>local studio — run & debug demos"]

    sdk -->|HTTPS + API key| platform
    sdk -->|depends on| shared
    tools -->|add_toolset| sdk
    studio -->|maivn studio CLI| sdk

    classDef current fill:#dbeafe,stroke:#2563eb,stroke-width:2px;
    class studio current;
```

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

## License

mAIvn Studio is **source-available** under the Business Source License 1.1 (BSL 1.1), not an OSI-approved open-source license. You may use it for any purpose, including production, except offering it as a commercial hosted service or redistributing it as a standalone product (see the Additional Use Grant in the license). On the Change Date (2030-03-11) it converts to the Apache License 2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE) for the full terms.
