graphmdo 0.2.0__tar.gz → 2.0.0__tar.gz

graphmdo-2.0.0/.github/workflows/latest-dependencies.yml

@@ -0,0 +1,26 @@
+name: Latest Allowed Dependencies
+
+on:
+  schedule:
+    - cron: "0 5 * * 0"
+  workflow_dispatch:
+
+jobs:
+  test-latest:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Upgrade dependency resolution
+        run: uv lock --upgrade
+      - name: Install upgraded dependencies
+        run: uv sync --all-extras --dev
+      - name: Run test suite
+        env:
+          PYTHONPATH: .
+        run: uv run pytest tests/

graphmdo-2.0.0/.github/workflows/quality.yml

@@ -0,0 +1,100 @@
+name: Quality Checks
+
+on: [push, pull_request]
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install dependencies
+        run: uv sync --frozen --all-extras --dev
+      - name: Run Ruff
+        run: uv run ruff check .
+      - name: Run Tests
+        env:
+          PYTHONPATH: .
+        run: uv run pytest -m "not e2e" --cov=src/mdo_framework --cov=src/services --cov-report=xml tests/
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: ./coverage.xml
+          flags: unit
+          fail_ci_if_error: false
+
+  e2e:
+    name: End-to-end regression suite (real Ax + GEMSEO)
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install dependencies
+        run: uv sync --frozen --all-extras --dev
+      - name: Run end-to-end tests
+        env:
+          OMP_NUM_THREADS: "1"
+          PYTHONPATH: .
+        run: uv run pytest -m e2e --durations=10 --cov=src/mdo_framework --cov=src/services --cov-report=xml tests/
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: ./coverage.xml
+          flags: e2e
+          fail_ci_if_error: false
+
+  wheel-smoke:
+    name: Installed wheel optimization smoke test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build wheel
+        run: uv build
+      - name: Create clean environment
+        run: uv venv --python 3.12 .venv-wheel-smoke
+      - name: Install wheel and test runner without lockfile
+        run: uv pip install --python .venv-wheel-smoke dist/*.whl pytest
+      - name: Run installed-wheel smoke test
+        run: .venv-wheel-smoke/bin/python -m pytest tests/smoke/test_installed_wheel.py -q
+
+  compose-smoke:
+    name: Docker Compose walkthrough smoke test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Start the stack and wait for healthy services
+        run: docker compose up -d --build --wait --wait-timeout 300
+      - name: Image has no dev dependencies
+        run: |
+          if docker compose exec -T graph-service python -c "import pytest"; then
+            echo "pytest must not be installed in the runtime image"; exit 1
+          fi
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+      - name: Replay the documented walkthrough
+        run: uv run --no-project --python 3.12 --with httpx python tests/smoke/compose_walkthrough.py
+      - name: Service logs
+        if: failure()
+        run: docker compose logs
+      - name: Tear down
+        if: always()
+        run: docker compose down -v

graphmdo-2.0.0/.github/workflows/security.yml

@@ -0,0 +1,55 @@
+name: Security Scan
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
+jobs:
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      security-events: write
+    steps:
+      - name: Free Disk Space (Ubuntu)
+        uses: jlumbroso/free-disk-space@main
+        with:
+          tool-cache: false
+          android: true
+          dotnet: true
+          haskell: true
+          large-packages: true
+          docker-images: true
+          swap-storage: true
+
+      - name: Setup Docker
+        uses: docker/setup-buildx-action@v3
+
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Build an image from Dockerfile
+        run: |
+          docker build -t docker.io/my-organization/my-app:${{ github.sha }} .
+
+      - name: Scan image for vulnerabilities
+        uses: anchore/scan-action@v7.4.2
+        id: scan
+        with:
+          image: 'docker.io/my-organization/my-app:${{ github.sha }}'
+          fail-build: true
+          severity-cutoff: high
+          output-format: sarif
+          only-fixed: true
+
+      - name: Upload vulnerability report
+        uses: github/codeql-action/upload-sarif@v4
+        if: always() && steps.scan.outputs.sarif != ''
+        with:
+          sarif_file: ${{ steps.scan.outputs.sarif }}

{graphmdo-0.2.0 → graphmdo-2.0.0}/.gitignore

@@ -201,12 +201,17 @@ cython_debug/
 .cursorignore
 .cursorindexingignore
 
+# VS Code settings
+.vscode/
+.agents/
+
 # Marimo
 marimo/_static/
 marimo/_lsp/
 __marimo__/
 
-# OpenMDAO Test Artifacts
+# GEMSEO Test Artifacts
 pytest*_out/
-*.openmdao_out
 reports/
+xdsm.html
+opt_history*.png

graphmdo-2.0.0/AGENTS.md

@@ -0,0 +1,105 @@
+# AGENTS.md
+
+## Strict Coding Standards
+
+1.  **PEP 20 (The Zen of Python)**
+    -   Explicit is better than implicit.
+    -   Simple is better than complex.
+    -   Readability counts.
+
+2.  **PEP 8 (Style Guide for Python Code)**
+    -   Indentation: 4 spaces.
+    -   Line Length: 88 characters.
+    -   Naming Conventions:
+        -   Functions/Variables: `lowercase_with_underscores`
+        -   Classes: `CapitalizedWords`
+        -   Constants: `ALL_CAPS_WITH_UNDERSCORES`
+    -   Imports: Standard library, third-party, local application.
+    -   Type Hinting: Use explicit Python 3 type hints.
+
+3.  **Typing and Interfaces**
+    -   Target Python 3.12+ syntax (`X | None`, `list[str]`, `dict[str, Any]`).
+    -   Keep FastAPI request/response contracts explicit with Pydantic models.
+    -   Prefer small, composable functions over hidden side effects.
+
+## Current Codebase Overview
+
+-   `main.py` is the local paraboloid demo wiring `GraphManager` -> `GraphProblemBuilder` -> `LocalEvaluator` -> `BayesianOptimizer`.
+-   `src/mdo_framework/schema.py` defines the typed `StudySchema` contract (`RangeVar`, `ChoiceVar`, `FixedParam`, `StateVar`, `ToolNode`, `Finding`, `ValidationReport`, `StudyValidationError`).
+-   `src/mdo_framework/validation.py` holds `validate_study()` (preflight against a request) and `validate_registry()` (tool registry and signature checks); `core/dependencies.py` is the shared dependency walk.
+-   `src/mdo_framework/db/` contains the FalkorDB integration (`client.py`, `graph_manager.py`).
+-   `src/mdo_framework/core/` contains schema-to-GEMSEO translation and execution helpers (`components.py`, `dependencies.py`, `errors.py`, `evaluators.py`, `mda.py`, `surrogates.py`, `topology.py`, `translator.py`).
+-   `src/mdo_framework/optimization/` contains the optimizer orchestration (`optimizer.py`), the backend-neutral Bayesian-optimization driver (`bo_library.py`, `bo_types.py`, `errors.py`) and its backends: Ax (`ax_algo_lib.py`) and a seeded random search (`random_search.py`).
+-   `src/services/graph/main.py` exposes the typed Graph Service API: `POST/PUT/DELETE` on `/variables` and `/tools`, `/connections/input`, `/connections/output`, `/schema`, `/clear`, `/health`. Conflicts return `409`, unknown nodes `404`, invalid bodies `422`.
+-   `src/services/execution/main.py` exposes the Execution Service API: `/evaluate`, `/health`, plus schema caching, a registry check on each loaded schema (`422` `SCHEMA_INVALID`), and pooled problem instances.
+-   `src/services/optimization/main.py` exposes the Optimization Service API: `/optimize` (with a `422` validation preflight), `/validate`, `/health`.
+-   `src/services/errors.py` registers the shared request-validation handler (`422` without echoing input) on all three services.
+-   `tests/` covers the core modules, services, database layer, optimizer, topology, translator, and the top-level demo entry point.
+-   `tests/e2e/` holds the seeded, non-mocked Ax + GEMSEO regression suite (marker `e2e`); open bugs are pinned there as strict xfails.
+
+## Runtime Architecture
+
+1.  **Graph Layer**
+    -   FalkorDB stores variables, tools, and directed data-flow edges.
+    -   `GraphManager.get_study_schema()` returns the typed `StudySchema`, the canonical boundary exported to the rest of the system.
+
+2.  **Translation Layer**
+    -   `GraphProblemBuilder` builds GEMSEO problems from the `StudySchema`: one `ToolComponent` per tool (strict output contract, finite-difference Jacobians) chained in a `StrictMDAChain` (`core/mda.py`).
+    -   Coupled tools run sequentially (Gauss-Seidel) by default; `MDASettings` selects the algorithm, and a coupled group that does not converge raises `MDANotConvergedError`.
+    -   `TopologicalAnalyzer` resolves dependencies and extracts optimization parameters from requested outputs.
+
+3.  **Evaluation Layer**
+    -   Local execution uses `LocalEvaluator`.
+    -   Remote execution uses the Execution Service, which maintains a `SchemaProvider` cache and a `ProblemPool` of initialized GEMSEO problems.
+
+4.  **Optimization Layer**
+    -   `BayesianOptimizer` builds the GEMSEO scenario and runs a `BaseBOLibrary` backend (`Ax_Bayesian` by default, `BO_RandomSearch`).
+    -   `BaseBOLibrary` owns the budget (`n_init + n_steps`, plus x0 when evaluated), stopping, failure classification, the guarded start point, user-name metric bindings and constraint feasibility; backends implement only `_setup`, `_ask` and `_tell`.
+
+5.  **Service Deployment**
+    -   `docker-compose.yml` runs FalkorDB plus three FastAPI services.
+    -   Default ports are 8001 (graph), 8002 (execution), and 8003 (optimization).
+
+## Implementation Directives
+
+-   **StudySchema Is the Source of Truth**: Flow data from FalkorDB through `get_study_schema()` into validation, topology analysis, translation, and services. Do not reintroduce untyped dict schemas.
+-   **Validate Before Running**: Study-level checks belong in `validate_study()` and tool-registry checks in `validate_registry()`; add new findings there with a stable error code and document them in `docs/technical-reference/study-schema.md`.
+-   **Keep the Published JSON Schema in Sync**: After changing `schema.py`, regenerate `docs/technical-reference/study-schema.json` with the command printed by `tests/test_docs_schema.py`.
+-   **Preserve Design Variable Order**: Keep FalkorDB insertion order for design variables; do not sort parameter names alphabetically before execution or optimization.
+-   **Use Keyword-Based Tool Invocation**: Wrapped tool functions must receive named inputs, not positional fallbacks that can scramble graph-defined ordering.
+-   **Raise Typed Evaluation Errors**: A point that cannot be evaluated raises an `EvaluationError` subclass from `core/errors.py` (`ToolExecutionError`, `ToolOutputError`, `MDANotConvergedError`), never a bare exception or a silently returned invalid value; services serialize them with `to_payload()`.
+-   **Keep Optimization State Explicit**: The library's `result` (`BORunResult`: trial records, stop reason, best trial, Pareto front) is the authoritative optimization output; avoid hidden cross-object attributes.
+-   **Keep Backends Thin**: Stopping, NaN handling, x0, metric naming and feasibility belong in `BaseBOLibrary`; a new backend implements only `_setup`, `_ask` and `_tell` and must pass the shared contract tests.
+-   **Respect Constraint Semantics**: Current optimization code uses GEMSEO/Ax convention `g(x) <= 0`; the paraboloid example encodes `c_xy = x - y`.
+-   **Extend Service Infrastructure, Do Not Bypass It**: Schema refresh/backoff belongs in `SchemaProvider`; reusable GEMSEO instances belong in `ProblemPool`.
+-   **Preserve Service Boundaries**: Cross-service calls should flow through `GRAPH_SERVICE_URL` and `EXECUTION_SERVICE_URL`, matching local and Docker Compose deployment.
+
+## Dependency Management
+
+-   This project uses `uv` for dependency management.
+-   Core runtime stack includes FalkorDB, FastAPI, GEMSEO, SMT, Ax Platform, BoTorch, pymoo, httpx, and NumPy/SciPy.
+-   Install project dependencies with `uv sync`.
+-   Install development dependencies with `uv sync --all-extras --dev`.
+-   Add a dependency with `uv add <package_name>`.
+-   Run commands in the environment with `uv run <command>`.
+-   **Do not use pip install manually.**
+
+## Development Commands
+
+-   Run the local demo: `uv run python main.py`
+-   Start the Graph Service: `uv run uvicorn services.graph.main:app --host 0.0.0.0 --port 8001`
+-   Start the Execution Service: `uv run uvicorn services.execution.main:app --host 0.0.0.0 --port 8002`
+-   Start the Optimization Service: `uv run uvicorn services.optimization.main:app --host 0.0.0.0 --port 8003`
+-   Start the full stack with containers: `docker compose up --build`
+
+## Validation and Docs
+
+-   Run all tests with `uv run pytest tests/`.
+-   Run fast unit tests with `uv run pytest -m "not e2e" tests/`.
+-   Run the real Ax + GEMSEO suite with `OMP_NUM_THREADS=1 uv run pytest -m e2e tests/`.
+-   Tests that pin an open bug are `xfail(strict=True)` with the issue number in the
+    reason; the PR that fixes the bug removes the marker.
+-   Run lint checks with `uv run ruff check .`.
+-   Format code with `uv run ruff format .`.
+-   Serve documentation locally with `uv run mkdocs serve`.
+-   Documentation lives under `docs/` and is built with MkDocs Material.

graphmdo-2.0.0/Dockerfile

@@ -0,0 +1,56 @@
+# Stage 1: Build stage
+FROM python:3.12-slim AS builder
+
+# Grab uv directly from astral's image
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /bin/
+
+# Docker-specific uv optimizations
+ENV UV_COMPILE_BYTECODE=1
+ENV UV_LINK_MODE=copy
+
+# Pass a dummy version to setuptools-scm during the docker build to prevent failures
+ENV SETUPTOOLS_SCM_PRETEND_VERSION="0.0.0"
+
+WORKDIR /app
+
+# Copy dependency files FIRST
+COPY pyproject.toml uv.lock README.md ./
+
+# Install dependencies into a virtual environment
+RUN uv sync --frozen --no-dev --no-install-project
+
+# Copy your source code
+COPY src/ src/
+
+# Install the project itself
+RUN uv sync --frozen --no-dev
+
+
+# Stage 2: Final runtime stage
+FROM python:3.12-slim
+
+# Update OS packages to fix vulnerabilities
+RUN apt-get update && apt-get upgrade -y && rm -rf /var/lib/apt/lists/*
+
+# Security: Ensure uv/uvx are NOT present in the final image
+RUN rm -f /usr/bin/uv /usr/bin/uvx /bin/uv /bin/uvx
+
+WORKDIR /app
+
+# Security: Create and use a non-root user
+RUN useradd -m appuser
+RUN chown appuser:appuser /app
+USER appuser
+
+# Copy the virtual environment and the source code from the builder stage
+COPY --from=builder --chown=appuser:appuser /app/.venv /app/.venv
+COPY --from=builder --chown=appuser:appuser /app/src /app/src
+
+# Set environment variables to use the virtual environment
+ENV PATH="/app/.venv/bin:$PATH"
+
+# Graph, execution and optimization services (see docker-compose.yml)
+EXPOSE 8001 8002 8003
+
+# Default command
+CMD ["uvicorn", "services.graph.main:app", "--host", "0.0.0.0", "--port", "8001"]