cosmos-synthia 0.1.0__tar.gz

cosmos_synthia-0.1.0/.github/workflows/deploy.yml

@@ -0,0 +1,63 @@
+name: Publish Python 🐍 distribution 📦 to PyPI
+
+on:
+  push:
+    tags:
+      - "v*.*.*" # Matches version tags like v1.0.0, v2.1.3, etc.
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    # Grant the job permission to request an OIDC token
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - name: Check out the repository
+        uses: actions/checkout@v5
+        with:
+          persist-credentials: false
+          # hatch-vcs derives the version from the tag, so the full
+          # history must be present; a shallow clone yields a dev version.
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.10"
+
+      - name: Install build dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+
+      - name: Build source distribution and wheel
+        run: python -m build
+
+      - name: Store the distribution packages
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish-to-pypi:
+    name: >-
+      Publish Python 🐍 distribution 📦 to PyPI
+    needs:
+      - build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi-deployment
+      url: https://pypi.org/p/cosmos-synthia
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download all the dists
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+      - name: Publish distribution 📦 to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

cosmos_synthia-0.1.0/.github/workflows/python-app.yml

@@ -0,0 +1,35 @@
+name: Synthia
+
+on:
+  pull_request:
+    branches: ["main"]
+  push:
+    branches: ["main"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      max-parallel: 2
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v7
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install '.[test]'
+      - name: Check Python formatting and linting
+        run: |
+          ruff format --check --diff .
+          ruff check .
+      - name: Test with pytest
+        run: pytest

cosmos_synthia-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+dist/
+build/
+*.egg-info/
+/benchmarks/results/
+
+# Generated at build time from the git tag
+src/synthia/_version.py

cosmos_synthia-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,20 @@
+# Run repository checks before changes are committed.
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: check-merge-conflict
+      - id: check-case-conflict
+      - id: check-added-large-files
+      - id: check-toml
+      - id: check-yaml
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.15
+    hooks:
+      - id: ruff-check
+        args:
+          - --fix
+      - id: ruff-format

cosmos_synthia-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,99 @@
+# Contributing
+
+Synthia follows Synthesizer's development and documentation standards.
+
+## Development Environment
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -e '.[dev,test]'
+pre-commit install
+```
+
+Install both extras, not just `dev`. They are deliberately separate: `dev`
+carries the linters and `pre-commit`, `test` carries `pytest`. `pip install
+-e '.[dev]'` alone leaves you without a test runner.
+
+## Required Checks
+
+```bash
+ruff check .
+ruff format --check .
+pytest
+```
+
+Most Synthesizer-specific tests skip when `cosmos-synthesizer` is not
+importable. Run the suite a second time in an environment that has it, as CI
+does, before claiming a change is covered:
+
+```bash
+pytest -q                     # Synthesizer absent
+/path/to/synth-env/bin/pytest -q   # Synthesizer present
+```
+
+`pre-commit run --all-files` runs repository hygiene, linting, and formatting
+checks together. CI runs the same checks, plus a wheel build.
+
+## Python Style
+
+- Follow PEP 8 and the repository Ruff configuration (79-character lines).
+- Write Google-style docstrings for public modules, classes, methods, and
+  functions.
+- Use `snake_case` for variables and functions and `PascalCase` for classes.
+- Add focused tests for non-trivial behaviour and bug fixes.
+
+## Documentation
+
+Synthia has no separate documentation site. `README.md` is the single source
+of truth for installation, tool behaviour and usage — update it in the same
+change that alters any of them. `PLAN.md` records design intent and open work
+only; do not restate tool behaviour there.
+
+Bundled skill references and examples are product behaviour. Keep them concise,
+version-aware, and tested where executable.
+
+Do not document a tool as available before it is implemented. Anything blocked
+on the remote grid catalogue service must stay explicitly marked as planned.
+
+## Packaging: the skill must reach the wheel
+
+Synthia's entire packaging story is that the bundled skill ships inside the
+distribution. Everything under `src/synthia/skill/` — `SKILL.md`, every
+reference, every example — must be present in the built wheel and resolvable
+through `importlib.resources` after a clean install.
+
+Hatchling ships every file under the selected package directory, so no
+`package_data`, `MANIFEST.in`, or `force-include` is needed. There is one
+sharp edge:
+
+> **Hazard: `.gitignore` can silently eat the skill.** Hatchling's default
+> file selection honours VCS ignore files. A broad pattern in `.gitignore` —
+> `examples/`, `*.md`, `references/`, a bare `docs/` — will quietly drop
+> matching skill files from the wheel. The package still imports, the tests
+> still pass under an editable install, and users get a skill with holes in
+> it. Before adding a `.gitignore` pattern, check it cannot match anything
+> under `src/synthia/skill/`.
+
+`tests/test_server.py` checks that `skill/SKILL.md` resolves, but under an
+editable install that check passes trivially by reading the source tree; it
+cannot catch a build-configuration regression. The wheel job in CI is the real
+guard: it builds the distribution, installs it into a clean environment away
+from the source tree, and asserts the packaged skill resources resolve. If you
+change build configuration or `.gitignore`, verify locally too:
+
+```bash
+python -m pip install build   # not in any extra
+python -m build
+python -m venv /tmp/synthia-wheel-check
+/tmp/synthia-wheel-check/bin/python -m pip install dist/*.whl
+cd /tmp && /tmp/synthia-wheel-check/bin/python -c "
+from importlib.resources import files
+skill = files('synthia') / 'skill'
+assert (skill / 'SKILL.md').is_file()
+assert (skill / 'references' / 'concepts.md').is_file()
+"
+```
+
+Run that check from outside the repository. Inside it, `src/` on the path can
+mask a missing file.

cosmos_synthia-0.1.0/INSTALL.md

@@ -0,0 +1,38 @@
+# Install Synthia
+
+These instructions are for the coding agent reading this file. Install Synthia
+for the user; do not merely describe the commands.
+
+1. Use the Python environment containing the user's `cosmos-synthesizer`
+   installation. Check with:
+
+   ```bash
+   python -c "import sys, synthesizer; print(sys.executable); print(synthesizer.__file__)"
+   ```
+
+   If this fails, ask which environment contains Synthesizer. Do not use
+   `pipx`, `uv tool install`, `sudo`, or a separate environment: Synthia must
+   import Synthesizer from the same environment.
+
+2. Install Synthia and run its idempotent setup command:
+
+   ```bash
+   python -m pip install cosmos-synthia
+   synthia-install
+   ```
+
+   The distribution is named `cosmos-synthia`; the import name is `synthia`.
+   Install from `git+https://github.com/synthesizer-project/synthia.git`
+   instead only if the user asks for an unreleased change.
+
+3. Report the environment and server paths printed by `synthia-install`, plus
+   any warnings or refusals. Do not use `--force` without asking the user: it
+   can replace an existing skill or MCP configuration owned by them.
+
+4. Tell the user to restart their agent client. After restart, verify the
+   installation by asking Synthia's `inspect_environment` tool for the
+   Synthesizer version and path.
+
+`synthia-install --dry-run` previews changes. `synthia-install --uninstall`
+removes the skill and MCP registrations; run it before uninstalling the Python
+package.