maivn-studio 0.2.0__tar.gz

maivn_studio-0.2.0/.claude/launch.json

@@ -0,0 +1,12 @@
+{
+  "version": "0.0.1",
+  "configurations": [
+    {
+      "name": "studio-frontend",
+      "runtimeExecutable": "npm",
+      "runtimeArgs": ["run", "dev"],
+      "cwd": "frontend",
+      "port": 5173
+    }
+  ]
+}

maivn_studio-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,65 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - master
+      - main
+  workflow_dispatch:
+
+concurrency:
+  group: maivn-studio-ci-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: npm
+          cache-dependency-path: frontend/package-lock.json
+
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      - name: Sync environment
+        run: uv sync --frozen
+
+      - name: Validate OSS license report
+        run: uv run --no-sync python scripts/oss_license_audit.py
+
+      - name: Ruff
+        run: uv run --no-sync ruff check .
+
+      - name: Pyright
+        run: uv run --no-sync pyright
+
+      - name: Pytest
+        run: uv run --no-sync pytest
+
+      - name: Install frontend dependencies
+        working-directory: frontend
+        run: npm ci
+
+      - name: Build frontend bundle
+        working-directory: frontend
+        run: npm run build
+
+      - name: Build wheel
+        run: uv build --wheel
+
+      - name: Validate wheel contents
+        run: uv run --no-sync python scripts/check_wheel_contents.py dist/*.whl

maivn_studio-0.2.0/.github/workflows/publish-pypi.yml

@@ -0,0 +1,57 @@
+name: Publish PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+concurrency:
+  group: maivn-studio-pypi-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: npm
+          cache-dependency-path: frontend/package-lock.json
+
+      - uses: astral-sh/setup-uv@v6
+
+      - name: Validate release version
+        run: uv run --with packaging --no-project python scripts/release_guard.py
+
+      - name: Install frontend dependencies
+        working-directory: frontend
+        run: npm ci
+
+      - name: Build frontend bundle
+        working-directory: frontend
+        run: npm run build
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Validate wheel contents
+        run: uv run --with packaging --no-project python scripts/check_wheel_contents.py dist/*.whl
+
+      - name: Validate distributions
+        run: uvx twine check dist/*
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

maivn_studio-0.2.0/.gitignore

@@ -0,0 +1,58 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+/lib/
+/lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+
+# Type checking
+.mypy_cache/
+.pyright/
+
+# Build artifacts
+*.log
+.ruff_cache/
+
+# Frontend
+node_modules/
+.svelte-kit/
+.env.local
+.env.*.local
+
+# Frontend build output (SvelteKit adapter-static)
+src/maivn_studio/static/_app/
+src/maivn_studio/static/index.html

maivn_studio-0.2.0/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2026-05-01
+
+### Added
+
+- **App catalog browser** in the sidebar with collapsible categories, search filtering, and executor type badges (Swarm/Agent). Surfaces source badges (Auto/Config) to distinguish discovered vs. configured apps.
+- **Light theme** with full Material Design 3 token system synced across portal/website. Theme preference persists in localStorage; inline script prevents FOUC.
+- **Schedule mode** in the chat composer with inline prompt configuration; new `prompt_text` field on `ScheduleConfig`.
+- **Schedule management** API and UI for cron-based app execution, including `ScheduleRunCard` and `ScheduleRunsView` components.
+- **Batch matrix execution** for running structured-output sweeps across variants.
+- **Tool-result redaction chip** persisted across sessions; private-data redaction badges rendered across UI components.
+- **Variant-aware private-data defaults** with prompt synchronization.
+- **`.env` file loading** at startup.
+
+### Changed
+
+- **Breaking: Demo → App rename** across the HTTP API, module paths, and frontend types:
+  - HTTP endpoints: `/api/demos` → `/api/apps`
+  - Query parameters: `demo_id` → `app_id`
+  - Python modules: `maivn_studio.api.routes.demos` → `...apps`, `services.demo_loader` → `services.app_loader`
+  - Frontend types: `Demo` / `DemoDetails` / `DemoVariant` → `App` / `AppDetails` / `AppVariant`
+- Removed `StudioEventBridge` subclass in favor of `EventBridge` configuration.
+- Refreshed `ScopeGroupHeaderIcon` visuals.
+
+### Fixed
+
+- Studio app resources now close cleanly on shutdown.
+- `release_loaded_demo` no longer closes `Agent` instances it did not create.
+
+## [0.1.0] - Initial release
+
+- Local studio for discovering, running, and debugging mAIvn SDK apps.
+- Session manager, prompt registry, structured-output inspector, and chat composer.

maivn_studio-0.2.0/DEPLOYMENT.md

@@ -0,0 +1,82 @@
+# Deployment
+
+## Repo Role
+
+`maivn-studio` is the public Studio companion package for the `maivn` SDK. It
+ships the Studio backend, static frontend bundle, and `maivn-studio` console
+script. End users install it directly:
+
+```bash
+pip install maivn-studio
+```
+
+Release `maivn-studio` only after the target `maivn` and `maivn-shared`
+versions already exist on PyPI.
+
+## Platform Order
+
+Use this order for a clean rollout that validates the private services before
+you publish the public SDK packages:
+
+1. Tag or pin `maivn-shared` in GitHub so service repos can consume an immutable ref.
+2. Tag or pin `maivn-internal-shared` in GitHub and record the immutable ref that services will consume.
+3. Create the production Supabase project and apply the platform migration pipeline.
+4. Deploy `maivn-agents`.
+5. Deploy `maivn-server`.
+6. After service validation, publish `maivn-shared` to PyPI.
+7. Publish `maivn` to PyPI.
+8. Publish `maivn-studio` to PyPI.
+
+## GitHub Setup
+
+1. Create the repo as public.
+2. Set `main` as the protected default branch.
+3. Enable GitHub Actions.
+4. Create an environment named `pypi`.
+5. Configure PyPI Trusted Publishing for:
+   `.github/workflows/publish-pypi.yml`
+6. Set these optional repository variables if the companion repos live outside
+   the default owner or if you want CI pinned to non-default refs:
+   - `MAIVN_REPO`
+   - `MAIVN_REF`
+   - `MAIVN_SHARED_REPO`
+   - `MAIVN_SHARED_REF`
+
+## Release Steps
+
+1. Confirm the target `maivn` and `maivn-shared` versions are already
+   published on PyPI.
+2. Update the Studio version and, if needed, the dependency ranges in
+   `pyproject.toml`.
+3. Build the shipped frontend bundle:
+   ```bash
+   cd frontend
+   npm ci
+   npm run build
+   cd ..
+   ```
+4. Run local verification:
+   ```bash
+   uv sync --frozen
+   uv run --no-sync ruff check .
+   uv run --no-sync pyright
+   uv run --no-sync pytest
+   uv build --wheel
+   python scripts/check_wheel_contents.py dist/*.whl
+   ```
+5. Merge the release commit to `main`.
+6. Create and push an annotated tag such as `v0.1.0`.
+7. Confirm the `Publish PyPI` workflow succeeds.
+8. Verify installation from a clean environment:
+   ```bash
+   pip install maivn-studio==0.1.0
+   maivn-studio --help
+   maivn studio --help
+   ```
+
+## Rollback
+
+1. Yank the affected PyPI version if needed.
+2. Cut a new patch release with the corrected dependency ranges or package
+   contents.
+3. Do not change the contents behind an existing tag.

maivn_studio-0.2.0/LICENSE

@@ -0,0 +1,32 @@
+Business Source License 1.1
+
+Licensor:  mAIvn, LLC
+Licensed Work:  mAIvn Studio
+Change Date:  2030-03-11
+Change License:  Apache License, Version 2.0
+
+For the full BSL 1.1 license terms, see:
+https://mariadb.com/bsl11/
+
+Additional Use Grant:
+
+You may use the Licensed Work for any purpose, including production use,
+EXCEPT you may not:
+
+  1. Offer the Licensed Work as a commercial hosted service to third
+     parties (i.e., operate it as a managed developer-tool platform).
+
+  2. Redistribute, sublicense, or resell the Licensed Work or any
+     modified version of it as a standalone product.
+
+You MAY use the Licensed Work internally within your organization
+and for developing applications that interact with mAIvn services.
+
+On the Change Date above, or the fourth anniversary of the first
+publicly available distribution of a specific version of the
+Licensed Work under this License, whichever comes first, the
+Licensor hereby grants you rights under the terms of the Change
+License, and the rights granted under the Business Source License
+will terminate.
+
+Copyright 2024-2026 mAIvn, LLC. All Rights Reserved.

maivn_studio-0.2.0/NOTICE

@@ -0,0 +1,12 @@
+mAIvn Studio
+Copyright 2024-2026 mAIvn, LLC. All Rights Reserved.
+
+This product includes software developed by mAIvn, LLC
+(https://maivn.io/).
+
+This software is licensed under the Business Source License 1.1.
+On the Change Date (2030-03-11) the license converts to Apache
+License, Version 2.0. See LICENSE for full terms.
+
+This software makes use of third-party open source components.
+See THIRD_PARTY_LICENSES.md for full details.

maivn_studio-0.2.0/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: maivn-studio
+Version: 0.2.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.3.0,>=0.2.0
+Requires-Dist: maivn<0.3.0,>=0.2.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
+```

maivn_studio-0.2.0/README.md

@@ -0,0 +1,92 @@
+# 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
+```

maivn_studio-0.2.0/THIRD_PARTY_LICENSES.md

@@ -0,0 +1,113 @@
+# Third-Party Open Source License Report
+
+**Package**: maivn-studio
+**Distribution**: Public PyPI developer tool
+**Report Date**: 2026-05-02
+**Report Version**: 2.1
+
+---
+
+## Executive Summary
+
+This report is generated from the locked dependency graph (`uv export --locked`) and installed package metadata.
+First-party `maivn-*` packages are excluded from the third-party inventory.
+
+**Compliance Result**: PASS
+
+| Scope | Packages | Permissive | Weak Copyleft | Strong Copyleft | Non-OSI | Unknown |
+|-------|----------|------------|----------------|------------------|---------|---------|
+| Runtime | 49 | 47 | 2 | 0 | 0 | 0 |
+| Dev-only | 7 | 7 | 0 | 0 | 0 | 0 |
+
+---
+
+## Notable Findings
+
+- Runtime blockers detected: none
+- Runtime weak-copyleft packages: certifi, orjson
+- Dev-only non-OSI packages: none
+
+## Runtime Dependencies
+
+| Package | Version | Effective License | Category | Notes |
+|---------|---------|-------------------|----------|-------|
+| annotated-doc | 0.0.4 | MIT | Permissive |   |
+| annotated-types | 0.7.0 | MIT License | Permissive |   |
+| anyio | 4.13.0 | MIT | Permissive |   |
+| certifi | 2026.2.25 | Mozilla Public License 2.0 (MPL 2.0) | Weak Copyleft |   |
+| charset-normalizer | 3.4.6 | MIT | Permissive |   |
+| click | 8.3.1 | BSD-3-Clause | Permissive |   |
+| croniter | 6.2.2 | MIT | Permissive |   |
+| docstring-parser | 0.17.0 | MIT License | Permissive |   |
+| fastapi | 0.136.1 | MIT | Permissive |   |
+| h11 | 0.16.0 | MIT License | Permissive |   |
+| httpcore | 1.0.9 | BSD-3-Clause | Permissive |   |
+| httptools | 0.7.1 | MIT | Permissive |   |
+| httpx | 0.28.1 | BSD License | Permissive |   |
+| idna | 3.11 | BSD-3-Clause | Permissive |   |
+| jsonpatch | 1.33 | BSD License | Permissive |   |
+| jsonpointer | 3.1.0 | BSD License | Permissive |   |
+| langchain-core | 1.3.2 | MIT License | Permissive |   |
+| langchain-protocol | 0.0.12 | MIT License | Permissive |   |
+| langsmith | 0.7.37 | MIT | Permissive |   |
+| markdown-it-py | 4.0.0 | MIT License | Permissive |   |
+| mdurl | 0.1.2 | MIT License | Permissive |   |
+| orjson | 3.11.8 | MPL-2.0 AND (Apache-2.0 OR MIT) | Weak Copyleft |   |
+| packaging | 26.0 | Apache-2.0 OR BSD-2-Clause | Permissive |   |
+| prompt-toolkit | 3.0.52 | BSD License | Permissive |   |
+| pydantic | 2.13.3 | MIT | Permissive |   |
+| pydantic-core | 2.46.3 | MIT | Permissive |   |
+| pygments | 2.20.0 | BSD-2-Clause | Permissive |   |
+| python-dateutil | 2.9.0.post0 | BSD License OR Apache Software License | Permissive |   |
+| python-dotenv | 1.2.2 | BSD-3-Clause | Permissive |   |
+| pyyaml | 6.0.3 | MIT License | Permissive |   |
+| requests | 2.33.1 | Apache Software License | Permissive |   |
+| requests-toolbelt | 1.0.0 | Apache Software License | Permissive |   |
+| rich | 14.3.4 | MIT License | Permissive |   |
+| six | 1.17.0 | MIT License | Permissive |   |
+| sse-starlette | 2.1.3 | BSD License | Permissive |   |
+| starlette | 1.0.0 | BSD-3-Clause | Permissive |   |
+| tenacity | 9.1.4 | Apache Software License | Permissive |   |
+| typing-extensions | 4.15.0 | PSF-2.0 | Permissive |   |
+| typing-inspection | 0.4.2 | MIT | Permissive |   |
+| tzlocal | 5.3.1 | MIT License | Permissive |   |
+| urllib3 | 2.6.3 | MIT | Permissive |   |
+| uuid-utils | 0.14.1 | BSD-3-Clause | Permissive |   |
+| uvicorn | 0.46.0 | BSD-3-Clause | Permissive |   |
+| uvloop | 0.22.1 | Apache Software License OR MIT License | Permissive | metadata from PyPI |
+| watchfiles | 1.1.1 | MIT License | Permissive |   |
+| wcwidth | 0.6.0 | MIT | Permissive |   |
+| websockets | 15.0.1 | BSD License | Permissive |   |
+| xxhash | 3.6.0 | BSD License | Permissive |   |
+| zstandard | 0.25.0 | BSD-3-Clause | Permissive |   |
+
+---
+
+## Development-Only Dependencies
+
+These packages are not part of the production runtime image.
+
+| Package | Version | Effective License | Category | Notes |
+|---------|---------|-------------------|----------|-------|
+| iniconfig | 2.3.0 | MIT | Permissive |   |
+| nodeenv | 1.10.0 | BSD License | Permissive |   |
+| pluggy | 1.6.0 | MIT License | Permissive |   |
+| pyright | 1.1.409 | MIT | Permissive |   |
+| pytest | 9.0.3 | MIT | Permissive |   |
+| pytest-asyncio | 1.3.0 | Apache-2.0 | Permissive |   |
+| ruff | 0.15.12 | MIT | Permissive |   |
+
+---
+
+## Compliance Checklist
+
+- [x] No blocked runtime licenses detected (strong copyleft, non-OSI, or unknown).
+- [x] Weak-copyleft runtime dependencies are used unmodified.
+- [x] Dev-only non-OSI packages remain excluded from production artifacts.
+- [x] Committed license report is expected to stay in sync with `uv.lock`.
+
+---
+
+## Certification
+
+This report was generated from `uv export --locked` output and installed package metadata as of the report date above.