Merge pull request #10 from RAMP-Protocol/feature/sdk-libraries

Generated SDK types export (Pydantic + Zod) from the proto; money as exact decimal

Author: legendko

.github/workflows/proto-ci.yml

@@ -42,4 +42,6 @@ jobs:
       # (informational, pre-v1). The remark docs-guard step self-skips here because
       # node_modules is absent; docs-ci.yml owns the docs build.
       - name: gating sequence (scripts/ci-local.sh)
-        run: ./scripts/ci-local.sh
+        # sdk-types-ci.yml owns the Pydantic/Zod gate (path-filtered), so skip it here
+        # and keep this job the proto mirror. Locally ci-local.sh runs both.
+        run: RAMP_CI_SKIP_SDK_TYPES=1 ./scripts/ci-local.sh

.github/workflows/sdk-types-ci.yml

@@ -0,0 +1,75 @@
+name: sdk-types-ci
+
+# Drift gate for the generated TYPES EXPORT (Pydantic + Zod). Regenerates from the
+# proto via scripts/gen-sdk-types.sh and fails if the committed output differs — the
+# same regenerate-and-diff contract as the gen/ drift gate, for the SDK types. Runs
+# only when the proto, the descriptor, the generators, or the committed output change.
+on:
+  push:
+    branches: [main]
+    paths: &paths
+      - 'proto/**'
+      - 'gen/descriptor.binpb'
+      - 'scripts/gen-sdk-types.sh'
+      - 'scripts/check-canonical.sh'
+      - 'scripts/sdk-types/**'
+      - 'conformance/**'
+      - 'gen/python/**'
+      - 'gen/ts/**'
+      - '.github/workflows/sdk-types-ci.yml'
+  pull_request:
+    paths: *paths
+
+jobs:
+  sdk-types:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+      - uses: bufbuild/buf-setup-action@v1
+        with:
+          version: 1.66.1
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: regenerate types export
+        run: ./scripts/gen-sdk-types.sh
+
+      # Only the two generated files; wire/base.py is hand-written (the seam) and the
+      # vocab constants are generated by buf, gated separately.
+      - name: assert no drift
+        run: |
+          if ! git diff --exit-code -- gen/python/wire/models.py gen/ts/wire/schemas.ts; then
+            echo "::error::Generated types export is out of sync with the proto. Run scripts/gen-sdk-types.sh and commit gen/python/wire/models.py + gen/ts/wire/schemas.ts."
+            exit 1
+          fi
+
+      # Cross-language validation parity: the generated Pydantic models and Zod schemas
+      # must reach the SAME verdict as Go protovalidate on every case in the generated
+      # corpus (conformance/corpus/cases.json) — proving the proto -> JSON Schema ->
+      # client pipeline carries every field-level rule. The corpus is pinned to
+      # protovalidate by the Go conformance suite (proto-ci) and gated for drift there.
+      - name: Python (Pydantic) parity
+        run: |
+          python -m pip install -q "pydantic>=2.0" pytest
+          PYTHONPATH=gen/python pytest gen/python/tests -q
+
+      - name: TypeScript (Zod) parity
+        working-directory: gen/ts
+        run: |
+          npm install
+          npm test
+
+      # Canonical proto-JSON interop: each client re-serializes every valid corpus
+      # instance and the emission, read back through Go protojson, must decode to the
+      # same proto message as the original (incl. Timestamp/Duration). Reuses the
+      # .sdk-types-work venv + zod provisioned by gen-sdk-types.sh above.
+      - name: Canonical proto-JSON round-trip
+        run: ./scripts/check-canonical.sh

.gitignore

@@ -9,3 +9,5 @@ research-*.md
 
 # Local agent/review scratch — never ship AI-review artifacts in the protocol repo
 .claude/
+__pycache__/
+.sdk-types-work/

README.md

@@ -35,18 +35,44 @@ A working multi-language stack — Exchange (Go), Broker (Go), Edge (TypeScript)
 
 ## SDKs
 
+All three languages are generated from `proto/`: Go is native protobuf + Connect via
+`buf generate` (it is the server/runtime); the Python and TypeScript **types exports**
+— Pydantic models and Zod schemas — are generated from the same proto via JSON Schema
+by `scripts/gen-sdk-types.sh` (the two real consumers, the Python MCP shim and the
+TypeScript edge worker, cannot use protobuf natively). All three carry **registered
+vocabulary constants** per axis (`pricingunits`, `quotametrics`, `functiontokens`,
+`geographytokens`, `usertypes`) so consumers use typed constants and an
+`IsRegistered`/`isRegistered`/`is_registered` membership check instead of magic
+strings. The vocab is emitted from the single `(ramp.v1.vocab)` source in one pass, so
+the three languages cannot drift from each other.
+
 ### Go
 
 ```go
 import (
     rampv1 "github.com/RAMP-Protocol/protocol/gen/go/ramp/v1"
     "github.com/RAMP-Protocol/protocol/gen/go/ramp/v1/rampv1connect"
+    "github.com/RAMP-Protocol/protocol/gen/go/vocab/pricingunits"
 )
 ```
 
 ### TypeScript
 
-TypeScript message types and a Connect client are generated under [`gen/ts/`](gen/ts) (Protobuf-ES + Connect-ES); the [reference implementation](https://github.com/RAMP-Protocol/reference-implementation) shows them in use.
+Zod schemas for every message are generated under [`gen/ts/wire/schemas.ts`](gen/ts/wire/schemas.ts) (validated message types; the edge worker uses them for request validation), with vocabulary constants under [`gen/ts/vocab/`](gen/ts/vocab); the [reference implementation](https://github.com/RAMP-Protocol/reference-implementation) shows them in use.
+
+```typescript
+import { OfferSchema } from "@ramp-protocol/sdk/wire/schemas";
+import { pricingunits } from "@ramp-protocol/sdk/vocab/pricingunits";
+```
+
+### Python
+
+Pydantic v2 models for every message (extending the hand-written `wire.base.WireModel` seam) plus vocabulary constants are generated under [`gen/python/`](gen/python) (`pip install .` from that directory; see its [README](gen/python/README.md)).
+
+```python
+from wire.models import Offer, Pricing
+from vocab import pricingunits
+```
 
 ## License