update client api with heterogenous structs support (#4)

.github/workflows/build.yml

@@ -12,37 +12,52 @@ jobs:
 
   build:
     runs-on: ubuntu-latest
-    steps:
+    strategy:
+      matrix:
+        module: ["."]
 
+    steps:
       - uses: actions/setup-go@v5
         with:
-          go-version: "1.21"
+          go-version: "1.22"
 
       - uses: actions/checkout@v4
-     
+
       - name: go build
+        working-directory: ${{ matrix.module }}
         run: |
           go build ./...
     
       - name: go test
+        working-directory: ${{ matrix.module }}
         run: |
-          go test -v -coverprofile=profile.cov $(go list ./... | grep -v /examples/)
+          go test -coverprofile=profile.cov $(go list ./... | grep -v /examples/)
+        env:
+          ## GOPATH required to build serverless app inside unittest 
+          GOPATH: /home/runner/work/${{ github.event.repository.name }}/go
 
       - uses: shogo82148/actions-goveralls@v1
         continue-on-error: true
         with:
+          working-directory: ${{ matrix.module }}
           path-to-profile: profile.cov
+          flag-name: ${{ matrix.module }}
+          parallel: true
 
-      - uses: reecetech/version-increment@2023.10.2
-        id: version
-        with:
-          scheme: semver
-          increment: patch
-
-      - name: publish
+      - name: release
+        working-directory: ${{ matrix.module }}
         run: |
           git config user.name "GitHub Actions"
           git config user.email "github-actions@users.noreply.github.com"
-          git tag ${{ steps.version.outputs.v-version }}
-          git push origin -u ${{ steps.version.outputs.v-version }}
-
+          for mod in `grep -roh "const Version = \".*" * | grep -Eoh "([[:alnum:]]*/*){1,}v[0-9]*\.[0-9]*\.[0-9]*"`
+          do
+            git tag $mod 2> /dev/null && git push origin -u $mod 2> /dev/null && echo "[+] $mod" || echo "[ ] $mod"
+          done
+ 
+  finish:
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: shogo82148/actions-goveralls@v1
+        with:
+          parallel-finished: true

.github/workflows/check.yml

@@ -0,0 +1,59 @@
+##
+## Unit Tests & Coverage
+##
+name: check
+on:
+  pull_request:
+    types:
+      - opened
+      - synchronize
+
+jobs:
+
+  unit:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        module: ["."]
+
+
+    steps:
+      - uses: actions/setup-go@v5
+        with:
+          go-version: "1.22"
+
+      - uses: actions/checkout@v4
+
+      - name: go build
+        working-directory: ${{ matrix.module }}
+        run: |
+          go build ./...
+    
+      - name: go test
+        working-directory: ${{ matrix.module }}
+        run: |
+          go test -coverprofile=profile.cov $(go list ./... | grep -v /examples/)
+        env:
+          ## GOPATH required to build serverless app inside unittest 
+          GOPATH: /home/runner/work/${{ github.event.repository.name }}/go
+
+      - uses: shogo82148/actions-goveralls@v1
+        continue-on-error: true
+        with:
+          working-directory: ${{ matrix.module }}
+          path-to-profile: profile.cov
+          flag-name: ${{ matrix.module }}
+          parallel: true
+
+      - uses: dominikh/staticcheck-action@v1.3.1
+        with:
+          install-go: false
+          working-directory: ${{ matrix.module }}
+
+  finish:
+      needs: unit
+      runs-on: ubuntu-latest
+      steps:
+        - uses: shogo82148/actions-goveralls@v1
+          with:
+            parallel-finished: true

README.md

@@ -93,7 +93,7 @@ Using data structures typically involves a following workflow:
 
 A data structure can be seen as a typed algebraic abstraction that encompasses a collection of data values, the relationships between those values, and the operations or functions that can be applied to manipulate the data. In practical application development, each data structure must be uniquely identifiable to allow efficient access and manipulation. To facilitate this, the application uses a unique reference name called a CURIE (Compact Uniform Resource Identifier). The CURIE combines both the data structure type and a unique identifier, ensuring that the correct data structure is referenced throughout the workflow, enabling smooth interactions within the system.   
 
-See [tutorials](./examples/) for example usage.
+See [tutorials](https://github.com/kshard/optimum-tutorials/tree/main) for example usage.
 
 #### List data structures
 
@@ -110,7 +110,7 @@ example2                   2024-08-18 10:38:13 | PENDING  NjqOYyOkpMHfg3.6 | {}
 
 #### Create data structure instance
 
-Create new instance of data structure. See either documentation of supported
+Create new instance of data structure. See either [documentation](./doc/) of supported
 data structure or `optimum help` for details about configuration parameters.
 
 ```bash
@@ -155,11 +155,12 @@ optimum <type> remove -u $HOST -n <name>
 
 ### Supported data structures
 
-The library supports following data structures:
+The command library supports following data structures:
 * `hnsw` [Hierarchical Navigable Small World](./doc/hnsw.md)
+* `text` [Nearest Neighborhood Search](./doc/text.md)
 
 
-Continue with [examples and tutorials](./examples/).
+Continue with [examples and tutorials](https://github.com/kshard/optimum-tutorials/tree/main).
 
 Note: the command line is only support basic operation for data structure manipulation. Use Golang API for any advanced scenario.
 
@@ -174,31 +175,37 @@ Use `go get` to retrieve the library and add it as dependency to your applicatio
 go get -u github.com/kshard/optimum
 ```
 
+The client library support
+* `optimum` package is control plane to coordinate the instances lifecycle.
+* `optimum/surface` package is data plane for reading/writing Graph-based Nearest Neighbor N-dimensional Surface.
+* `optimum/sentences` package is data plane for reading/writing natural language text and searching for nearest neighbor.
+
+
 ### Quick Example
 
-The example below shows usage of client for Hierarchical Navigable Small World.
+The example below shows usage of client for reading natural language text.
 
 ```go
 package main
 
 import (
-  "github.com/kshard/optimum"
+  "github.com/kshard/optimum/sentences"
   "github.com/fogfish/gurl/v2/http"
   "github.com/fogfish/curie"
 )
 
 const (
   host = "https://example.com"
-  cask = curie.IRI("hnsw:example")
+  cask = curie.IRI("text:example")
 )
 
 func main() {
   // Create client, the library depends on 
-  api := optimum.New(http.New(), host)
+  api := sentences.New(http.New(), host)
 
   // Query the data structure
   neighbors, err := api.Query(context.Background(), cask,
-		optimum.Query{Query: []float32{0.1, 0.2, /* ... */ 0.128}},
+		sentences.Query{Text: "hello world!"},
 	)
 
   // Print results

go.mod

@@ -6,7 +6,7 @@ require (
 	github.com/fogfish/curie v1.8.2
 	github.com/fogfish/gurl/v2 v2.9.0
 	github.com/fogfish/schemaorg v1.22.0
-	github.com/kshard/wreck v0.0.1
+	github.com/kshard/wreck v0.0.2
 )
 
 require (

go.sum

@@ -12,7 +12,7 @@ github.com/fogfish/schemaorg v1.22.0 h1:0laPbToW8lVxdx7hPgc8qukZfrewBJYNf4ffpZn/
 github.com/fogfish/schemaorg v1.22.0/go.mod h1:CDOmEVSdag/o66Y3qjFROm0mUjJxDvSzAOXQwd+ZFrs=
 github.com/google/go-cmp v0.6.0 h1:ofyhxvXcZhMsU5ulbFiLKl/XBFqE1GSq7atu8tAmTRI=
 github.com/google/go-cmp v0.6.0/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
-github.com/kshard/wreck v0.0.1 h1:U/vucQnpA7IgIG01xiq/6/cy57lhn3T/vQXUI4lOXSU=
-github.com/kshard/wreck v0.0.1/go.mod h1:rT4tAEOaZhozTekFxTUhclfu4mLnqFgdrgrMtXw+KAI=
+github.com/kshard/wreck v0.0.2 h1:MUTbcLDmD0//p/S4iiKskzcKB5DgMJNeBfao1c+iiFk=
+github.com/kshard/wreck v0.0.2/go.mod h1:rT4tAEOaZhozTekFxTUhclfu4mLnqFgdrgrMtXw+KAI=
 golang.org/x/net v0.26.0 h1:soB7SVo0PWrY4vPW/+ay0jKDNScG2X9wFeYlXIvJsOQ=
 golang.org/x/net v0.26.0/go.mod h1:5YKkiSynbBIh3p6iOc/vibscux0x38BZDkn8sCUPxHE=

restapi.go

@@ -25,10 +25,11 @@ type Client struct {
 }
 
 func New(stack http.Stack, host string) *Client {
-	return &Client{
+	cli := &Client{
 		Stack: stack,
 		host:  ø.Authority(host),
 	}
+	return cli
 }
 
 func (api *Client) Casks(ctx context.Context, schema string) (*Instances, error) {
@@ -97,17 +98,3 @@ func (api *Client) Remove(ctx context.Context, cask curie.IRI) error {
 		),
 	)
 }
-
-func (api *Client) Query(ctx context.Context, cask curie.IRI, q Query) (*Result, error) {
-	return http.IO[Result](
-		api.WithContext(ctx),
-		http.GET(
-			ø.URI("%s/ds/%s/%s", api.host, curie.Prefix(cask), curie.Reference(cask)),
-			ø.Accept.JSON,
-			ø.ContentType.JSON,
-			ø.Send(q),
-
-			ƒ.Status.OK,
-		),
-	)
-}

sentences/sentences.go

@@ -0,0 +1,74 @@
+//
+// Copyright (C) 2024 Dmitry Kolesnikov
+//
+// This file may be modified and distributed under the terms
+// of the MIT license.  See the LICENSE file for details.
+// https://github.com/kshard/optimum
+//
+
+package sentences
+
+import (
+	"context"
+
+	"github.com/fogfish/curie"
+	"github.com/fogfish/gurl/v2/http"
+	ƒ "github.com/fogfish/gurl/v2/http/recv"
+	ø "github.com/fogfish/gurl/v2/http/send"
+)
+
+// Client for reading/writing natural language text and searching for nearest neighbor.
+type Client struct {
+	http.Stack
+
+	host ø.Authority
+}
+
+// Creates the client for reading/writing natural language text and searching for nearest neighbor.
+func New(stack http.Stack, host string) *Client {
+	return &Client{
+		Stack: stack,
+		host:  ø.Authority(host),
+	}
+}
+
+// Write the sentence
+func (api *Client) Write(ctx context.Context, cask curie.IRI, bag []Sentence) error {
+	if len(bag) == 0 {
+		return nil
+	}
+
+	return api.IO(ctx,
+		http.POST(
+			ø.URI("%s/ds/%s/%s/object", api.host, curie.Prefix(cask), curie.Reference(cask)),
+			ø.Accept.JSON,
+			ø.ContentType.JSON,
+			ø.Send(struct {
+				V []Sentence `json:"object"`
+			}{
+				V: bag,
+			}),
+
+			ƒ.Status.Accepted,
+		),
+	)
+}
+
+// Query nearest neighbor text to the given sample.
+func (api *Client) Query(ctx context.Context, cask curie.IRI, q Query) (*Result, error) {
+	return http.IO[Result](
+		api.WithContext(ctx),
+		http.GET(
+			ø.URI("%s/ds/%s/%s", api.host, curie.Prefix(cask), curie.Reference(cask)),
+			ø.Accept.JSON,
+			ø.ContentType.JSON,
+			ø.Send(struct {
+				Q Query `json:"query"`
+			}{
+				Q: q,
+			}),
+
+			ƒ.Status.OK,
+		),
+	)
+}