maestro-se 0.1.0__tar.gz

maestro_se-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,37 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync
+      - run: uv run mypy libs/ src/maestro/
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync
+      - run: uv run pytest libs/maestro-ssot/tests/ --cov --cov-report=xml -v
+      - run: uv run pytest libs/maestro-harness/tests/ --cov --cov-append --cov-report=xml -v
+      - run: uv run pytest libs/maestro-agents/tests/ --cov --cov-append --cov-report=xml -v
+      - run: uv run pytest libs/maestro-loop/tests/ --cov --cov-append --cov-report=xml -v
+      - run: uv run pytest tests/ --cov --cov-append --cov-report=xml -v

maestro_se-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,70 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write  # for creating GitHub Release
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+
+      - name: Build all packages
+        run: uv build --all-packages
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/maestro
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.PYPI_API_TOKEN }}
+        run: uv publish dist/*
+
+  github-release:
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true

maestro_se-0.1.0/.gitignore

@@ -0,0 +1,46 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+dist/
+build/
+
+# Virtual environments
+.venv/
+
+# Testing
+.pytest_cache/
+htmlcov/
+.coverage
+coverage.xml
+
+# Type checking
+.mypy_cache/
+.pyright/
+
+# Ruff
+.ruff_cache/
+
+# IDE
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# uv
+uv.lock
+
+# Project
+*.db
+*.sqlite3
+.maestro/
+src/api/
+
+# env
+.env

maestro_se-0.1.0/Dockerfile

@@ -0,0 +1,42 @@
+# MAESTRO-SSOT — Reproducible Experiment Environment
+# Usage:
+#   docker build -t maestro-ssot .
+#   docker run -it --rm -v $(pwd)/output:/output maestro-ssot maestro benchmark --output-dir /output
+
+FROM python:3.12-slim
+
+# Install system deps
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    git \
+    curl \
+    build-essential \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install uv
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
+
+WORKDIR /app
+
+# Copy project files
+COPY pyproject.toml uv.lock ./
+COPY libs/ ./libs/
+COPY src/ ./src/
+COPY tests/ ./tests/
+COPY benchmarks/ ./benchmarks/
+COPY scripts/ ./scripts/
+COPY configs/ ./configs/
+COPY docs/ ./docs/
+COPY README.md ./
+
+# Install dependencies
+RUN uv sync --frozen --no-dev
+
+# Create default global config
+RUN mkdir -p /root/.maestro && \
+    echo '[llm]\nprovider = "anthropic"\nmodel = "claude-sonnet-4-20250514"\nthinking = true\n' > /root/.maestro/config.toml
+
+ENV PATH="/app/.venv/bin:$PATH"
+
+# Default: show help
+ENTRYPOINT ["maestro"]
+CMD ["--help"]

maestro_se-0.1.0/Makefile

@@ -0,0 +1,47 @@
+.PHONY: help install test lint format typecheck demo dev status clean
+
+help: ## Show this help
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-15s\033[0m %s\n", $$1, $$2}'
+
+install: ## Install all dependencies
+	uv sync
+
+test: ## Run all tests
+	uv run pytest libs/maestro-ssot/tests/ -q
+	uv run pytest libs/maestro-harness/tests/ -q
+	uv run pytest libs/maestro-agents/tests/ -q
+	uv run pytest libs/maestro-loop/tests/ -q
+	uv run pytest tests/ -q
+
+lint: ## Run ruff linter
+	uv run ruff check .
+
+format: ## Run ruff formatter
+	uv run ruff format .
+
+typecheck: ## Run mypy type checker
+	uv run mypy libs/ src/maestro/
+
+check: lint format typecheck test ## Run all checks (lint + format + typecheck + test)
+
+demo: ## Run maestro demo
+	uv run maestro demo
+
+status: ## Run maestro status (requires project)
+	uv run maestro status
+
+dev: ## Hot-reload dev server (default: demo)
+	python scripts/dev-server.py demo
+
+dev-run: ## Hot-reload dev server with run --demo
+	python scripts/dev-server.py run --demo "Build a JWT auth system"
+
+dev-repl: ## Hot-reload dev server with REPL
+	python scripts/dev-server.py
+
+clean: ## Clean generated files
+	find . -type d -name __pycache__ -exec rm -rf {} +
+	find . -type d -name .pytest_cache -exec rm -rf {} +
+	find . -type d -name .mypy_cache -exec rm -rf {} +
+	find . -type d -name .ruff_cache -exec rm -rf {} +
+	find . -type f -name "*.pyc" -delete

maestro_se-0.1.0/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: maestro-se
+Version: 0.1.0
+Summary: Managed Autonomy in Multi-Agent Software Engineering via Single Source of Truth
+Requires-Python: >=3.12
+Requires-Dist: maestro-agents
+Requires-Dist: maestro-harness
+Requires-Dist: maestro-loop
+Requires-Dist: maestro-ssot
+Requires-Dist: prompt-toolkit>=3.0
+Requires-Dist: tomli-w>=1.2.0
+Requires-Dist: typer>=0.25

maestro_se-0.1.0/README.md

@@ -0,0 +1,268 @@
+<p align="center">
+  <img src="docs/banner.png" width="640" alt="MAESTRO-SSOT">
+</p>
+
+<p align="center">
+  <strong>Managed Autonomy in Multi-Agent Software Engineering<br>via Single Source of Truth</strong>
+</p>
+
+<p align="center">
+  <a href="https://github.com/HYPERVAPOR/maestro-ssot/actions/workflows/ci.yml">
+    <img src="https://img.shields.io/github/actions/workflow/status/HYPERVAPOR/maestro-ssot/ci.yml?branch=main&label=CI" alt="CI">
+  </a>
+  <img src="https://img.shields.io/badge/python-3.12+-blue.svg" alt="Python 3.12+">
+  <img src="https://img.shields.io/badge/code%20size-3.9k%20LOC-informational" alt="Code Size">
+  <img src="https://img.shields.io/badge/tests-147%20passing-brightgreen" alt="Tests">
+  <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License">
+</p>
+
+<p align="center">
+  A multi-agent framework where specialized LLM agents collaborate around a <strong>shared structured state</strong> instead of passing messages — coordinated by an autonomous control loop and guarded by a restrictive execution harness.
+</p>
+
+---
+
+## Why MAESTRO?
+
+Current multi-agent coding systems (AutoGen, ChatDev) treat collaboration as **message passing**: agents work in isolation, then reconcile post-hoc. This causes integration failures, redundant communication, and opaque execution.
+
+Real engineering teams use **shared artifacts** — issue trackers, API specs, design docs. MAESTRO brings this model to AI agents:
+
+- **SSOT Hub** — a SQLite-backed shared state for requirements, contracts, execution logs, and agent memory
+- **Agent Harness** — file ACLs, command filtering, token/step budgets, and dangerous pattern detection
+- **File & Shell Tools** — agents read/write actual files and execute shell commands through the sandbox
+- **Auto-Loop** — an LLM-driven controller that plans, assigns, executes, validates, and commits autonomously
+- **Real-time Observability** — streaming thinking content and tool calls as they happen
+
+<p align="center">
+  <img src="docs/architecture.png" width="640" alt="System Architecture">
+</p>
+
+## Quick Start
+
+### Install (one line)
+
+```bash
+curl -sSL https://raw.githubusercontent.com/HYPERVAPOR/maestro-ssot/main/scripts/install.sh | bash
+```
+
+Or manually with `uv`:
+
+```bash
+uv tool install git+https://github.com/HYPERVAPOR/maestro-ssot.git
+```
+
+### Run a task (any directory)
+
+```bash
+# Demo mode (deterministic, no LLM calls)
+maestro run --demo "Implement JWT user authentication"
+
+# Real LLM execution (requires API key)
+maestro run "Implement JWT user authentication"
+```
+
+MAESTRO auto-creates a `.maestro/` project directory on first use (Claude Code-style).
+
+### Interactive REPL
+
+```bash
+maestro
+```
+
+```
+╭──────────────────────────────────────────────────────────────────╮
+│  MAESTRO-SSOT v0.1.0                                             │
+│  Project: my-project (/home/user/my-project)                     │
+│  Model: claude-sonnet-4-20250514                                 │
+│  DB: .maestro/ssot.db (3 requirements)                           │
+╰──────────────────────────────────────────────────────────────────╯
+
+maestro> task Add user profile page with avatar upload
+maestro> status
+maestro> contracts
+maestro> help
+maestro> quit
+```
+
+### Evaluate & Benchmark
+
+```bash
+# Single-task comparison: MAESTRO vs baselines vs ablations
+maestro eval "Implement a Todo REST API"
+
+# Run only specific methods
+maestro eval "Implement a Todo REST API" --method maestro-ssot --method single-agent
+
+# Full Contract-Bench suite (10 tasks × 5 methods)
+maestro benchmark --output-dir ./results
+
+# Dry run to see what would be executed
+maestro benchmark --dry-run
+```
+
+### View project status
+
+```bash
+maestro status
+```
+
+Displays a Rich-formatted view of the requirement tree, contract registry, and execution log.
+
+### Initialize explicitly (optional)
+
+```bash
+maestro init . --name "my-project"
+```
+
+Most commands work without explicit `init` — the project is created lazily on first use.
+
+## Docker
+
+Build and run in a reproducible container:
+
+```bash
+# Build
+docker build -t maestro-ssot .
+
+# Run benchmark
+docker run -it --rm \
+  -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
+  -v $(pwd)/output:/output \
+  maestro-ssot benchmark --output-dir /output
+
+# Or use docker-compose
+docker-compose run maestro
+```
+
+## Architecture
+
+| Package           | Role                                                                                 | Dependencies                      |
+| ----------------- | ------------------------------------------------------------------------------------ | --------------------------------- |
+| `maestro-ssot`    | Shared state hub — requirements, contracts, logs, memory, versioning, access control | None                              |
+| `maestro-harness` | Safety layer — file ACL, command filtering, budgets, sandbox, validator              | None                              |
+| `maestro-agents`  | Role agents — Planner, Backend, Frontend, Test, Review                               | `maestro-ssot`, `maestro-harness` |
+| `maestro-loop`    | Autonomous controller — LLM-driven controller, scheduler, retry budget               | All above                         |
+| `maestro` (root)  | CLI + TUI — Typer commands, Rich output, interactive REPL                            | All above                         |
+
+### Key Design Principles
+
+1. **Shared state over messages** — Agents read/write a structured SSOT, not chat logs
+2. **Guarded execution** — Every agent action passes through ACL → validator → budget → sandbox
+3. **Observable by default** — All mutations are logged; snapshots enable rollback
+4. **Testable without LLMs** — PydanticAI TestModel enables deterministic CI testing
+5. **Resilient by design** — Timeouts, retries, and graceful degradation on API failures
+
+## Configuration
+
+### Global: `~/.maestro/config.toml`
+
+```toml
+[llm]
+provider = "anthropic"
+model = "claude-sonnet-4-20250514"
+thinking = true  # Stream agent thinking content
+
+[display]
+verbose = false
+log_level = "INFO"
+```
+
+### Project: `.maestro/config.toml`
+
+```toml
+[project]
+name = "my-project"
+
+[harness]
+policy = ".maestro/policy.yaml"
+
+[[agents]]
+role = "planner"
+
+[[agents]]
+role = "backend"
+```
+
+### Harness Policy: `.maestro/policy.yaml`
+
+```yaml
+agents:
+  backend-1:
+    filesystem:
+      allow: ["src/**", "tests/**", "libs/**"]
+      deny: ["**/.env", "**/secrets*"]
+    commands:
+      allow: ["python*", "pytest*", "ruff*", "mypy*"]
+    budget:
+      max_tokens_per_task: 60000
+      max_steps_per_epoch: 20
+      max_wall_time_minutes: 10
+```
+
+## Contract-Bench
+
+MAESTRO includes a built-in benchmark suite for evaluating multi-agent SE systems:
+
+```bash
+# List available tasks
+python -c "from benchmarks.contract_bench.tasks import ALL_TASKS; print([t.TASK_ID for t in ALL_TASKS])"
+
+# Evaluate a single task programmatically
+from benchmarks.contract_bench.tasks import TASK_01_JWT_AUTH
+result = TASK_01_JWT_AUTH.evaluate("./my-project")
+print(result.score, result.passed)
+```
+
+| Task | Description | Difficulty | Modules |
+|------|-------------|------------|---------|
+| CB-01 | JWT Auth + Login Page | Easy | backend, frontend |
+| CB-02 | Todo API + SQLite + React | Medium | backend, frontend, database |
+| CB-03 | Chat WebSocket + Redis | Hard | backend, frontend, messaging |
+| CB-04 | User CRUD API | Easy | backend |
+| CB-05 | File Upload/Download | Easy | backend, frontend |
+| CB-06 | Payment Gateway | Medium | backend, frontend |
+| CB-07 | Real-time Notifications (SSE) | Medium | backend, frontend |
+| CB-08 | Full-text Search Engine | Medium | backend, frontend |
+| CB-09 | Microservices Order System | Hard | backend, database, messaging |
+| CB-10 | Collaborative Editor (OT/CRDT) | Hard | backend, frontend |
+
+## Development
+
+```bash
+# Install with dev dependencies
+uv sync
+
+# Run all checks
+uv run ruff check .              # lint
+uv run ruff format --check .     # format
+uv run mypy libs/ src/maestro/   # type-check
+
+# Run tests (per-package to avoid conftest collision)
+uv run pytest libs/maestro-ssot/tests/
+uv run pytest libs/maestro-harness/tests/
+uv run pytest libs/maestro-agents/tests/
+uv run pytest tests/
+```
+
+## Project Status
+
+| Phase     | Description                                                        | Status  |
+| --------- | ------------------------------------------------------------------ | ------- |
+| Phase 1   | SSOT core, Harness, Agents, CLI, TUI, REPL                         | Done    |
+| Phase 1.5 | CLI productization, Rich output, project management                | Done    |
+| Phase 2   | LLM-driven Controller, streaming output, Contract-Bench v1         | Done    |
+| Phase 2.5 | Resilience layer (timeouts, retries), TUI animations               | Done    |
+| Phase 3   | 10-task benchmark, baselines, ablation studies, data pipeline      | Done    |
+| Phase 3.6 | Agent file/shell tools, SWE-bench style task validation            | Done    |
+| Phase 4   | Paper submission (ICSE/FSE/ASE)                                    | In Progress |
+
+## Research
+
+This project is the reference implementation for our research on multi-agent software engineering. See the [research proposal](docs/rp.md) for the full technical motivation.
+
+**Core hypothesis**: Explicit shared-state mediation (SSOT) combined with runtime guardrails (Harness) enables multi-agent SE systems to achieve higher integration success rates and lower communication overhead than message-passing alternatives.
+
+## License
+
+MIT

maestro_se-0.1.0/RELEASING.md

@@ -0,0 +1,149 @@
+# Releasing MAESTRO-SSOT
+
+## Prerequisites
+
+1. **PyPI account** with `maestro-se`, `maestro-ssot`, `maestro-harness`, `maestro-loop`, `maestro-agents` package names registered (or reserved).
+2. **GitHub Repository** with Trusted Publishing configured:
+   - Go to [PyPI → Account → Publishing](https://pypi.org/manage/account/publishing/)
+   - Add a new pending publisher:
+     - **PyPI Project Name**: `maestro-se`
+     - **Owner**: `HYPERVAPOR`
+     - **Repository name**: `maestro-ssot`
+     - **Workflow name**: `release.yml`
+     - **Environment name**: `pypi`
+   - Repeat for each workspace package: `maestro-ssot`, `maestro-harness`, `maestro-loop`, `maestro-agents`
+
+> Alternatively, you can use a PyPI API token stored as a GitHub secret (`PYPI_API_TOKEN`) and modify `.github/workflows/release.yml` to use `uv publish --token $PYPI_TOKEN` instead of `--trusted-publishing always`.
+
+## Release Steps
+
+### 1. Update the version
+
+```bash
+# Edit version in all pyproject.toml files
+# Root package
+sed -i 's/version = "0.1.0"/version = "0.2.0"/' pyproject.toml
+# Lib packages
+for f in libs/*/pyproject.toml; do
+  sed -i 's/version = "0.1.0"/version = "0.2.0"/' "$f"
+done
+```
+
+Or use a script:
+
+```bash
+./scripts/bump-version.sh 0.2.0
+```
+
+### 2. Update CHANGELOG (optional)
+
+```bash
+# Add release notes to CHANGELOG.md
+```
+
+### 3. Commit and tag
+
+```bash
+git add -A
+git commit -m "release: v0.2.0"
+git tag v0.2.0
+git push origin main
+git push origin v0.2.0
+```
+
+### 4. CI handles the rest
+
+The `release.yml` workflow will automatically:
+1. Build wheels and source distributions for all workspace packages
+2. Publish them to PyPI via trusted publishing
+3. Create a GitHub Release with auto-generated notes and attached artifacts
+
+### 5. Verify
+
+Wait for the workflow to complete (~2 minutes), then verify:
+
+```bash
+# Check PyPI
+curl -s https://pypi.org/pypi/maestro-se/json | python -c "import sys,json; print(json.load(sys.stdin)['info']['version'])""
+
+# Test install
+uv tool install maestro-se
+maestro --version
+```
+
+## Local Build & Test (without publishing)
+
+```bash
+# Build all packages
+uv build --all-packages
+
+# Inspect the built artifacts
+ls -la dist/
+
+# Test install from local build
+uv tool install --reinstall dist/maestro-*.whl
+maestro --version
+```
+
+## One-Line Install
+
+After a release is published, users can install MAESTRO with:
+
+```bash
+# Via install.sh (auto-detects uv/pipx/pip)
+curl -sSL https://raw.githubusercontent.com/HYPERVAPOR/maestro-ssot/main/scripts/install.sh | bash
+
+# Or directly with uv
+uv tool install maestro
+
+# Or with pipx
+pipx install maestro-se
+
+# Or with pip
+pip install --user maestro-se
+```
+
+### Uninstall
+
+```bash
+curl -sSL https://raw.githubusercontent.com/HYPERVAPOR/maestro-ssot/main/scripts/install.sh | MAESTRO_UNINSTALL=1 bash
+```
+
+## Troubleshooting
+
+### Trusted Publishing fails
+
+If the `publish-pypi` job fails with an authentication error:
+1. Verify the PyPI pending publisher configuration matches exactly (owner, repo, workflow name, environment)
+2. Check that the `permissions: id-token: write` is set in the workflow
+3. As a fallback, create a PyPI API token and add it as a GitHub secret named `PYPI_API_TOKEN`, then update the workflow:
+   ```yaml
+   - name: Publish to PyPI
+     run: uv publish --token ${{ secrets.PYPI_API_TOKEN }} dist/*
+   ```
+
+### Package name conflicts on PyPI
+
+The root package is published as `maestro-se` because `maestro` is already occupied on PyPI (by a vision-language model tool). The CLI command remains `maestro` regardless of the PyPI package name.
+
+If any other package names are taken, you can:
+1. Use a different namespace
+2. Request a name transfer from the current owner
+3. Use a private index (e.g., GitHub Packages, private PyPI)
+
+### Install.sh fails
+
+Test locally before pushing:
+```bash
+bash scripts/install.sh
+```
+
+With a specific version:
+```bash
+MAESTRO_VERSION=0.2.0 bash scripts/install.sh
+```
+
+With uninstall:
+```bash
+MAESTRO_UNINSTALL=1 bash scripts/install.sh
+```

maestro_se-0.1.0/benchmarks/swebench_task/pyproject.toml

@@ -0,0 +1,11 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "dateutils"
+version = "0.1.0"
+dependencies = []
+
+[tool.setuptools.packages.find]
+where = ["src"]