Skip to content

Commit 391d7d1

Browse files
linfangwgemini-code-assist[bot]
linfangw
and
gemini-code-assist[bot]
authored
feat: add ecosystem templates and manifest validation (#36)
* feat(ecosystem): add recipes and manifest validation * test(ecosystem): cover manifest validator failures * Update recipes/crypto-monitoring/README.md Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> * Update recipes/data-analysis/README.md Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> * Update recipes/developer-automation/README.md Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> * Update recipes/finance-research/README.md Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> * Update recipes/risk-compliance/README.md Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> * fix(ecosystem): align manifest validator with schema --------- Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
1 parent 7aa6b3e commit 391d7d1

22 files changed

Lines changed: 1971 additions & 0 deletions

‎.github/workflows/ecosystem-validate.yml‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
name: Validate ecosystem manifests
2+
3+
on:
4+
pull_request:
5+
paths:
6+
- "ecosystem/**"
7+
- "recipes/**"
8+
- "scripts/validate-ecosystem-manifests.mjs"
9+
- "scripts/test-ecosystem-validator.mjs"
10+
- ".github/workflows/ecosystem-validate.yml"
11+
push:
12+
branches:
13+
- main
14+
paths:
15+
- "ecosystem/**"
16+
- "recipes/**"
17+
- "scripts/validate-ecosystem-manifests.mjs"
18+
- "scripts/test-ecosystem-validator.mjs"
19+
- ".github/workflows/ecosystem-validate.yml"
20+
21+
permissions:
22+
contents: read
23+
24+
jobs:
25+
validate:
26+
runs-on: ubuntu-latest
27+
28+
steps:
29+
- name: Checkout
30+
uses: actions/checkout@v4
31+
32+
- name: Setup Node.js
33+
uses: actions/setup-node@v4
34+
with:
35+
node-version: 20
36+
37+
- name: Validate manifests
38+
run: node scripts/validate-ecosystem-manifests.mjs
39+
40+
- name: Test manifest validator
41+
run: node scripts/test-ecosystem-validator.mjs

‎.github/workflows/python-sdk-publish.yml‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
name: Publish Python SDK to PyPI
2+
3+
on:
4+
push:
5+
tags:
6+
- "python-sdk-v*" # Trigger on tags like python-sdk-v0.1.0, python-sdk-v1.0.0
7+
8+
permissions:
9+
contents: write # For creating GitHub Releases
10+
11+
jobs:
12+
test:
13+
runs-on: ubuntu-latest
14+
defaults:
15+
run:
16+
working-directory: packages/python-sdk
17+
18+
strategy:
19+
matrix:
20+
python-version: ["3.10", "3.11", "3.12"]
21+
22+
steps:
23+
- name: Checkout
24+
uses: actions/checkout@v4
25+
26+
- name: Setup Python ${{ matrix.python-version }}
27+
uses: actions/setup-python@v5
28+
with:
29+
python-version: ${{ matrix.python-version }}
30+
31+
- name: Setup uv
32+
uses: astral-sh/setup-uv@v5
33+
with:
34+
enable-cache: true
35+
cache-dependency-glob: packages/python-sdk/uv.lock
36+
37+
- name: Run tests
38+
run: uv run --extra dev pytest
39+
40+
- name: Compile package and examples
41+
run: uv run python -m compileall qveris examples
42+
43+
publish:
44+
needs: test
45+
runs-on: ubuntu-latest
46+
defaults:
47+
run:
48+
working-directory: packages/python-sdk
49+
50+
steps:
51+
- name: Checkout
52+
uses: actions/checkout@v4
53+
54+
- name: Setup Python
55+
uses: actions/setup-python@v5
56+
with:
57+
python-version: "3.11"
58+
59+
- name: Setup uv
60+
uses: astral-sh/setup-uv@v5
61+
with:
62+
enable-cache: true
63+
cache-dependency-glob: packages/python-sdk/uv.lock
64+
65+
- name: Verify package version matches tag
66+
run: |
67+
TAG_VERSION="${GITHUB_REF_NAME#python-sdk-v}"
68+
PKG_VERSION=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml', 'rb'))['project']['version'])")
69+
if [ "$TAG_VERSION" != "$PKG_VERSION" ]; then
70+
echo "::error::Tag version ($TAG_VERSION) does not match pyproject.toml version ($PKG_VERSION)"
71+
exit 1
72+
fi
73+
echo "VERSION=$PKG_VERSION" >> "$GITHUB_ENV"
74+
75+
- name: Build package
76+
run: uv build
77+
78+
- name: Publish to PyPI
79+
uses: pypa/gh-action-pypi-publish@release/v1
80+
with:
81+
packages-dir: packages/python-sdk/dist
82+
password: ${{ secrets.PYPI_API_TOKEN }}
83+
84+
- name: Create GitHub Release
85+
uses: softprops/action-gh-release@v2
86+
with:
87+
name: "QVeris Python SDK v${{ env.VERSION }}"
88+
body: |
89+
## Install
90+
91+
```bash
92+
pip install qveris==${{ env.VERSION }}
93+
```
94+
95+
## Highlights
96+
97+
- Publishes the typed Python SDK for the QVeris Agent External Data & Tool Harness.
98+
- Includes discover, inspect, call, usage, and ledger client methods.
99+
- Includes the built-in agent runtime and OpenAI-compatible provider support.
100+
101+
See [README](packages/python-sdk/README.md) for usage.
102+
generate_release_notes: true

‎README.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -266,6 +266,12 @@ This repository (`QVerisAI/qveris-agent-toolkit`) is the primary monorepo for QV
266266
| Agent docs | [`agent/`](agent) | — |
267267
| Skills | [`skills/`](skills) | — |
268268
269+
### Recipes and ecosystem manifests
270+
271+
Use [`recipes/`](recipes) for copy-paste workflow templates across finance research, risk/compliance, crypto monitoring, data analysis, and developer automation.
272+
273+
Use [`ecosystem/`](ecosystem) for the versioned QVeris manifest schema, marketplace-ready listing fields, permission declarations, contribution guide, and compatibility matrix.
274+
269275
### Other repositories
270276
271277
| Repository | Description |

‎ecosystem/CONTRIBUTING.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# Ecosystem Contribution Guide
2+
3+
Use this guide for adding QVeris recipes, skills, plugins, or marketplace listing metadata.
4+
5+
## Add A Recipe
6+
7+
1. Create a directory under `recipes/<kebab-case-name>/`.
8+
2. Add `README.md` with a copy-paste complete CLI path and a Python SDK path when relevant.
9+
3. Add `qveris.manifest.json` using `ecosystem/manifest.schema.json`.
10+
4. Declare every permission needed by the workflow:
11+
- `capability.discover` for finding capabilities.
12+
- `capability.inspect` for reading parameter, billing, and quality metadata.
13+
- `capability.call` only when the recipe executes a capability.
14+
- `capability.audit` when the recipe reads usage history or credits ledger data.
15+
5. Add marketplace fields that can be consumed by a future listing service.
16+
6. Run `node scripts/validate-ecosystem-manifests.mjs`.
17+
18+
## Metadata Rules
19+
20+
- Keep `id` stable once published.
21+
- Use semver for `version`.
22+
- Set `status` to `experimental`, `beta`, or `stable`.
23+
- Keep `summary` under 160 characters.
24+
- Prefer product-neutral use-case language in `marketplace.use_cases`.
25+
- Do not declare a permission unless the workflow needs it.
26+
27+
## Compatibility
28+
29+
Update [`compatibility.md`](compatibility.md) when a recipe requires a newer CLI, MCP, Python SDK, skill, or plugin surface.
30+
31+
## Review Checklist
32+
33+
- Manifest validates locally.
34+
- README commands are copy-paste complete.
35+
- Example paths in the manifest exist.
36+
- Permission reasons explain the user-facing need.
37+
- Marketplace fields are suitable for website ingestion without rewriting.

‎ecosystem/README.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# QVeris Ecosystem Manifests
2+
3+
QVeris ecosystem entries use a versioned manifest to describe recipes, skills, plugins, and marketplace-ready listings with the same metadata surface.
4+
5+
The current schema is [`manifest.schema.json`](manifest.schema.json), version `2026-05-13`.
6+
7+
## What The Manifest Covers
8+
9+
- Identity: stable `id`, `kind`, `name`, `version`, and lifecycle `status`.
10+
- Marketplace listing fields: `listing_slug`, `headline`, `audience`, `use_cases`, `integration_methods`, and `primary_cta`.
11+
- Permissions: QVeris capability scopes, network hosts, local files, and secrets.
12+
- Compatibility: minimum CLI, MCP, Python SDK, skill, or plugin versions.
13+
- Docs and examples: required local README plus runnable or copy-paste complete commands.
14+
15+
## Validation
16+
17+
Run the validator from the repository root:
18+
19+
```bash
20+
node scripts/validate-ecosystem-manifests.mjs
21+
```
22+
23+
Validate a specific manifest or directory:
24+
25+
```bash
26+
node scripts/validate-ecosystem-manifests.mjs recipes/finance-research/qveris.manifest.json
27+
node scripts/validate-ecosystem-manifests.mjs recipes
28+
```
29+
30+
CI runs the same validator on recipe, schema, and validator changes. A manifest fails validation when required metadata is missing, permission declarations are incomplete, examples point at missing docs, or marketplace listing fields are absent.
31+
32+
Run validator regression tests:
33+
34+
```bash
35+
node scripts/test-ecosystem-validator.mjs
36+
```
37+
38+
## Manifest Templates
39+
40+
- [`templates/skill-manifest.template.json`](templates/skill-manifest.template.json)
41+
- [`templates/plugin-manifest.template.json`](templates/plugin-manifest.template.json)
42+
43+
Use these as starting points, then replace every placeholder before committing a real `qveris.manifest.json`.
44+
45+
## Related Docs
46+
47+
- [Contribution guide](CONTRIBUTING.md)
48+
- [Compatibility matrix](compatibility.md)
49+
- [Recipes](../recipes/README.md)

‎ecosystem/compatibility.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Ecosystem Compatibility Matrix
2+
3+
The ecosystem manifest is designed to keep recipes, skills, plugins, and marketplace listings aligned across QVeris integration surfaces.
4+
5+
| Surface | Minimum version | Used for |
6+
|---------|-----------------|----------|
7+
| Manifest schema | `2026-05-13` | Shared metadata, permissions, docs, examples, and marketplace listing fields |
8+
| QVeris CLI | `>=0.5.0` | `discover`, `inspect`, `call`, `usage`, `ledger`, and `init` recipe commands |
9+
| QVeris MCP server | `>=0.6.0` | Canonical MCP tools plus usage and credits ledger audit tools |
10+
| QVeris Python SDK | `>=0.1.0` | Typed `QverisClient`, `Agent`, and audit methods |
11+
| QVeris agent skill | `>=0.1.0` | Agent-facing discover, inspect, call, and audit workflow guidance |
12+
13+
## Compatibility Policy
14+
15+
- Recipe manifests should declare every surface they depend on.
16+
- Existing recipe IDs remain stable across recipe version updates.
17+
- Deprecated tool aliases must not be used in new manifests or examples.
18+
- New required manifest fields require a new `schema_version`.
19+
- Additive marketplace fields may be introduced without invalidating the `2026-05-13` schema only when the validator treats them as optional.

0 commit comments

Comments
 (0)