Merge pull request #2 from structured-world/fix/#1-sdk-api-correctness

fix: SDK API correctness — constructor, cypher result, VectorResult fields

Author: polaz

.github/workflows/ci.yml

@@ -10,46 +10,40 @@ jobs:
     name: Lint
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
 
-      - uses: actions/setup-python@v5
+      - uses: astral-sh/setup-uv@38f3f104447c67c051c4a08e39b64a148898af3a  # v4
         with:
           python-version: "3.11"
 
-      - run: pip install ruff
-      - run: ruff check coordinode/ langchain-coordinode/ llama-index-coordinode/ tests/
-      - run: ruff format --check coordinode/ langchain-coordinode/ llama-index-coordinode/ tests/
+      - run: uv sync
+      - run: uv run ruff check coordinode/ langchain-coordinode/ llama-index-coordinode/ tests/
+      - run: uv run ruff format --check coordinode/ langchain-coordinode/ llama-index-coordinode/ tests/
 
   test:
     name: Test (Python ${{ matrix.python-version }})
     runs-on: ubuntu-latest
     strategy:
+      fail-fast: false
       matrix:
-        python-version: ["3.9", "3.11", "3.12"]
+        python-version: ["3.11", "3.12", "3.13"]
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
         with:
           submodules: recursive
 
-      - uses: actions/setup-python@v5
+      - uses: astral-sh/setup-uv@38f3f104447c67c051c4a08e39b64a148898af3a  # v4
         with:
           python-version: ${{ matrix.python-version }}
 
-      - name: Install protoc
-        run: sudo apt-get update && sudo apt-get install -y protobuf-compiler
-
-      - name: Install packages
-        run: |
-          pip install grpcio-tools
-          pip install -e "coordinode[dev]"
-          pip install -e langchain-coordinode/
-          pip install -e llama-index-coordinode/
+      - name: Install dependencies
+        run: uv sync
 
       - name: Generate proto stubs
-        run: make proto
+        run: uv run make proto
 
       - name: Unit tests
-        run: pytest tests/unit/ -v
+        run: uv run pytest tests/unit/ -v
 
   test-integration:
     name: Integration tests
@@ -60,30 +54,36 @@ jobs:
         ports:
           - 7080:7080
           - 7084:7084
-        options: >-
-          --health-cmd "wget -qO- http://localhost:7084/health || exit 1"
-          --health-interval 10s
-          --health-timeout 5s
-          --health-retries 12
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
         with:
           submodules: recursive
 
-      - uses: actions/setup-python@v5
+      - uses: astral-sh/setup-uv@38f3f104447c67c051c4a08e39b64a148898af3a  # v4
         with:
           python-version: "3.11"
 
-      - name: Install protoc
-        run: sudo apt-get update && sudo apt-get install -y protobuf-compiler
+      - name: Wait for coordinode
+        run: |
+          echo "Waiting for coordinode to be ready (HTTP :7084 + gRPC :7080)..."
+          for i in $(seq 1 30); do
+            if curl -sf http://localhost:7084/health >/dev/null 2>&1 && \
+               (echo > /dev/tcp/localhost/7080) 2>/dev/null; then
+              echo "coordinode is ready (attempt $i)"
+              exit 0
+            fi
+            echo "Attempt $i/30 — not ready yet, sleeping 5s..."
+            sleep 5
+          done
+          echo "Error: coordinode did not become healthy after 150s" >&2
+          exit 1
 
       - name: Install + generate proto
         run: |
-          pip install grpcio-tools
-          pip install -e "coordinode[dev]"
-          make proto
+          uv sync
+          uv run make proto
 
       - name: Integration tests
         env:
           COORDINODE_ADDR: "localhost:7080"
-        run: pytest tests/integration/ -v --timeout=30
+        run: uv run pytest tests/integration/ -v --timeout=30

.github/workflows/release-please.yml

@@ -0,0 +1,20 @@
+name: Release Please
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: googleapis/release-please-action@16a9c90856f42705d54a6fda1823352bdc62cf38  # v4
+        id: rp
+        with:
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json

.github/workflows/release.yml

@@ -1,8 +1,9 @@
 name: Release
 
-# Triggered manually: create a tag v0.3.0 → GitHub Release → this workflow publishes to PyPI.
-# Tag format:  v{MAJOR}.{MINOR}.{PATCH}     → stable, publishes to PyPI
-#              v{MAJOR}.{MINOR}.{PATCH}a{N}  → pre-release, publishes to TestPyPI only
+# Triggered automatically by release-please (see release-please.yml):
+#   1. Merge release PR → release-please tags the commit → this workflow publishes to PyPI.
+# Tag format:  v{MAJOR}.{MINOR}.{PATCH}     → stable release
+#              v{MAJOR}.{MINOR}.{PATCH}a{N}  → pre-release (published to PyPI with --pre required)
 
 on:
   push:
@@ -26,65 +27,37 @@ jobs:
           - name: llama-index-graph-stores-coordinode
             path: llama-index-coordinode
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
         with:
           submodules: recursive
           fetch-depth: 0   # hatch-vcs needs full history for tag detection
 
-      - uses: actions/setup-python@v5
+      - uses: astral-sh/setup-uv@38f3f104447c67c051c4a08e39b64a148898af3a  # v4
         with:
           python-version: "3.11"
 
-      - name: Install protoc + build tools
-        run: |
-          sudo apt-get update && sudo apt-get install -y protobuf-compiler
-          pip install hatchling hatch-vcs grpcio-tools build
+      - name: Install build tools
+        run: uv sync
 
       - name: Generate proto stubs (coordinode only)
         if: matrix.package.name == 'coordinode'
-        run: make proto
+        run: uv run make proto
 
       - name: Build wheel + sdist
         working-directory: ${{ matrix.package.path }}
-        run: python -m build
+        run: uv run python -m build
 
       - name: Upload dist artifact
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02  # v4
         with:
           name: dist-${{ matrix.package.name }}
           path: ${{ matrix.package.path }}/dist/
           retention-days: 1
 
-  publish-testpypi:
-    name: Publish to TestPyPI (pre-release)
-    runs-on: ubuntu-latest
-    needs: build
-    if: contains(github.ref_name, 'a') || contains(github.ref_name, 'b') || contains(github.ref_name, 'rc')
-    environment: testpypi
-    permissions:
-      id-token: write
-    strategy:
-      matrix:
-        package:
-          - coordinode
-          - langchain-coordinode
-          - llama-index-graph-stores-coordinode
-    steps:
-      - uses: actions/download-artifact@v4
-        with:
-          name: dist-${{ matrix.package }}
-          path: dist/
-
-      - uses: pypa/gh-action-pypi-publish@release/v1
-        with:
-          repository-url: https://test.pypi.org/legacy/
-          packages-dir: dist/
-
   publish-pypi:
-    name: Publish to PyPI (stable)
+    name: Publish to PyPI
     runs-on: ubuntu-latest
     needs: build
-    if: "!contains(github.ref_name, 'a') && !contains(github.ref_name, 'b') && !contains(github.ref_name, 'rc')"
     environment: pypi
     permissions:
       id-token: write
@@ -95,12 +68,12 @@ jobs:
           - langchain-coordinode
           - llama-index-graph-stores-coordinode
     steps:
-      - uses: actions/download-artifact@v4
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093  # v4
         with:
           name: dist-${{ matrix.package }}
           path: dist/
 
-      - uses: pypa/gh-action-pypi-publish@release/v1
+      - uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b  # release/v1
         with:
           packages-dir: dist/
 
@@ -111,13 +84,13 @@ jobs:
     permissions:
       contents: write
     steps:
-      - uses: actions/download-artifact@v4
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093  # v4
         with:
           pattern: dist-*
           merge-multiple: true
           path: dist/
 
-      - uses: softprops/action-gh-release@v2
+      - uses: softprops/action-gh-release@153bb8e04406b158c6c84fc1615b65b24149a1fe  # v2
         with:
           prerelease: ${{ contains(github.ref_name, 'a') || contains(github.ref_name, 'b') || contains(github.ref_name, 'rc') }}
           generate_release_notes: true

.gitignore

@@ -1,5 +1,5 @@
 # Generated proto stubs — run `make proto` to regenerate
-coordinode/_proto/coordinode/
+coordinode/_proto/
 
 # Build artifacts
 dist/
@@ -18,5 +18,6 @@ env/
 
 # Version files generated by hatch-vcs
 coordinode/_version.py
-langchain_coordinode/_version.py
-llama_index/graph_stores/coordinode/_version.py
+langchain-coordinode/langchain_coordinode/_version.py
+llama-index-coordinode/llama_index/graph_stores/coordinode/_version.py
+GAPS.md

.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.3.0"
+}

Makefile

@@ -1,34 +1,45 @@
-.PHONY: proto proto-check install test test-unit test-integration lint clean
+.PHONY: proto proto-check install install-pip test test-unit test-integration lint clean
 
 PROTO_SRC  := proto
 PROTO_OUT  := coordinode/_proto
+PYTHON     ?= python3
 
 # Generate gRPC stubs from proto submodule into coordinode/_proto/
 proto:
 	@echo "==> Generating proto stubs..."
 	@mkdir -p $(PROTO_OUT)
-	python -m grpc_tools.protoc \
+	$(PYTHON) -m grpc_tools.protoc \
 		-I$(PROTO_SRC) \
 		--python_out=$(PROTO_OUT) \
 		--grpc_python_out=$(PROTO_OUT) \
 		--pyi_out=$(PROTO_OUT) \
 		$$(find $(PROTO_SRC) -name '*.proto')
 	@# Add __init__.py to every generated package directory
 	@find $(PROTO_OUT) -type d -exec touch {}/__init__.py \;
-	@# Fix relative imports in generated *_pb2_grpc.py files (grpc_tools generates absolute)
-	@find $(PROTO_OUT) -name '*_pb2_grpc.py' -exec sed -i '' \
-		's/^from coordinode\./from coordinode._proto.coordinode./g' {} \;
+	@# Fix absolute imports in all generated pb2 files (grpc_tools generates absolute paths)
+	@# sed -i.bak is portable: macOS needs empty-string backup arg, GNU sed uses -i alone;
+	@# using .bak suffix works on both, then we clean up the backup files.
+	@find $(PROTO_OUT) -name '*.py' -exec sed -i.bak \
+		's/from coordinode\.v1\./from coordinode._proto.coordinode.v1./g' {} \;
+	@find $(PROTO_OUT) -name '*.py.bak' -delete
 	@echo "==> Proto generation complete: $(PROTO_OUT)/"
 
 proto-check:
 	@test -f $(PROTO_OUT)/coordinode/v1/query/cypher_pb2.py || \
 		(echo "ERROR: Proto stubs not generated. Run: make proto" && exit 1)
 
-# Install all packages in editable mode for development
-install: proto
+# Install using uv (recommended for contributors).
+# uv sync runs first — it installs grpcio-tools which proto generation requires.
+install:
+	uv sync
+	$(MAKE) proto
+
+# Install using pip (alternative — works without uv)
+install-pip:
 	pip install -e "coordinode[dev]"
 	pip install -e langchain-coordinode/
 	pip install -e llama-index-coordinode/
+	$(MAKE) proto
 
 test: proto-check test-unit