diff --git a/docs.json b/docs.json index d3c5cb18..ea01decb 100644 --- a/docs.json +++ b/docs.json @@ -89,7 +89,6 @@ "modus/app-manifest", "modus/data-fetching", "modus/model-invoking", - "modus/search", "modus/api-generation", "modus/authentication", "modus/error-handling", @@ -107,7 +106,6 @@ "group": "AssemblyScript SDK", "pages": [ "modus/sdk/assemblyscript/overview", - "modus/sdk/assemblyscript/collections", "modus/sdk/assemblyscript/console", "modus/sdk/assemblyscript/dgraph", "modus/sdk/assemblyscript/graphql", @@ -123,7 +121,6 @@ "group": "Go SDK", "pages": [ "modus/sdk/go/overview", - "modus/sdk/go/collections", "modus/sdk/go/console", "modus/sdk/go/dgraph", "modus/sdk/go/graphql", @@ -503,10 +500,6 @@ "destination": "/introduction", "permanent": true }, - { - "source": "/modus/sdk/collections", - "destination": "/modus/sdk/assemblyscript/collections" - }, { "source": "/modus/sdk/console", "destination": "/modus/sdk/assemblyscript/console" diff --git a/getting-started-with-hyper-commerce.mdx b/getting-started-with-hyper-commerce.mdx index 8b9ed9f1..b662596c 100644 --- a/getting-started-with-hyper-commerce.mdx +++ b/getting-started-with-hyper-commerce.mdx @@ -120,10 +120,6 @@ In the Hypermode console, you’ll see several key components of your project: - **[Functions](/modus/overview):** These are serverless functions written in AssemblyScript (a TypeScript-like language) that are automatically exposed as GraphQL APIs. Once deployed, you can query these functions within your app. -- **[Collections](/modus/sdk/assemblyscript/collections):** Hypermode offers - built-in key-value storage, known as collections, with support for vector - embeddings. This allows you to store and retrieve data efficiently, without - requiring a database for basic use cases. - **[Models](/modus/sdk/assemblyscript/models):** This section represents the AI models defined for your project. These models handle tasks like embedding text into vectors for search. Hypermode provides open source shared and dedicated diff --git a/modus/app-manifest.mdx b/modus/app-manifest.mdx index 488413dc..d9ebc699 100644 --- a/modus/app-manifest.mdx +++ b/modus/app-manifest.mdx @@ -20,9 +20,6 @@ resources for your functions at runtime. You define the manifest in the Define inference services for use in your functions - - Define sets of text data to enable natural language search - ### Base manifest @@ -516,46 +513,3 @@ dedicated instance of the model. Your project's functions securely access the hosted model, with no further configuration required. - -## Collections - -Collections simplify the usage of vector embeddings to build natural language -search features. The `collections` object allows you to define indexed data -types that are automatically embedded and searchable based on the search method -you define. - -Each collection requires a unique name, specified as a key, containing only -alphanumeric characters and hyphens. - -For more detail on implementing Collections, see [Search](/modus/search). - -```json modus.json -{ - "collections": { - "myProducts": { - "searchMethods": { - "searchMethod": { - "embedder": "myEmbedder", - "index": { - "type": "sequential" - } - } - } - } - } -} -``` - - - Search methods define a pair of an embedder and index to make available for - searching the data in your collection. - - - - The function name to embed text added to the collection. - - - - If provided, describes the index mechanism used by the search method. `type`: - specifies the type of the index. For example, `sequential` (default). - diff --git a/modus/model-invoking.mdx b/modus/model-invoking.mdx index aa17feab..aafba0fe 100644 --- a/modus/model-invoking.mdx +++ b/modus/model-invoking.mdx @@ -256,5 +256,4 @@ export function classifyText(text: string, threshold: f32): string { Modus supports invoking embedding models for text, images, and other data types. You use the outputs of these models for implementing search, recommendation, and -similarity functions in your app. Refer to [Search](/modus/search) for more -information on how to use embeddings in your app. +similarity functions in your app. diff --git a/modus/overview.mdx b/modus/overview.mdx index 2eac70a6..ae5f9b49 100644 --- a/modus/overview.mdx +++ b/modus/overview.mdx @@ -52,6 +52,5 @@ A few of the core Modus features include: | [Multi-Language](/modus/project-structure) | Write functions in Go and AssemblyScript, with additional language support in development | | [Auto-Generated API](/modus/api-generation) | A secure API is automatically generated from your function signatures | | [Model Integration](/modus/model-invoking) | Connect and invoke AI models from different providers, without learning a new SDK | -| [Search](/modus/search) | Add natural language search and recommendations with integrated vector embeddings | | [Authentication](/modus/authentication) | Secure your API endpoints with minimal configuration | | **WebAssembly Runtime** | Small and portable execution engine for deployment across server, edge, and desktop computes | diff --git a/modus/project-structure.mdx b/modus/project-structure.mdx index f55fa7ee..3c0e071e 100644 --- a/modus/project-structure.mdx +++ b/modus/project-structure.mdx @@ -46,9 +46,9 @@ configuration separated from your source code. The `modus.json` [app manifest](/modus/app-manifest) is the central configuration file for your Modus app. It defines the endpoints, connections, -models, and collections that your code has available to it during runtime. -Because Modus is a secure-by-default framework, only the resources defined in -this file are accessible to your app. +and models that your code has available to it during runtime. Because Modus is a +secure-by-default framework, only the resources defined in this file are +accessible to your app. ## Initializing your app diff --git a/modus/run-locally.mdx b/modus/run-locally.mdx index 5579c24d..b9a9bae6 100644 --- a/modus/run-locally.mdx +++ b/modus/run-locally.mdx @@ -98,11 +98,3 @@ hyp login After logging in, your app automatically connects to Hypermode's [Model Router](/model-router) when running locally. - -## Working with Collections - -Collections requires a PostgreSQL instance for local development. While -Hypermode manages this database in production, you'll need to set up PostgreSQL -locally when developing outside the Hypermode platform. For detailed setup -instructions, see -[Develop locally with Collections](/modus/search#develop-locally-with-collections). diff --git a/modus/sdk/assemblyscript/collections.mdx b/modus/sdk/assemblyscript/collections.mdx deleted file mode 100644 index 65693efa..00000000 --- a/modus/sdk/assemblyscript/collections.mdx +++ /dev/null @@ -1,718 +0,0 @@ ---- -title: "Collections APIs" -sidebarTitle: "Collections" -description: "Add storage and vector search capabilities to your functions." -icon: "circle-small" -iconType: "solid" ---- - -import { SdkHeader } from "/snippets/sdk-header.mdx" -import SdkTip from "/snippets/sdk-tip.mdx" - - - -The Modus Collection APIs allow you to add vector search within your functions. - -## Import - -To begin, import the `collections` namespace from the SDK: - -```ts -import { collections } from "@hypermode/modus-sdk-as" -``` - -## Collections APIs - -{/* vale Google.Headings = NO */} - -The APIs in the `collections` namespace are below, organized by category. - - - -### Mutation Functions - -#### upsert - -Inserts or updates an item in a collection. - - - If the item already exists, the function overwrites the previous value. If - not, it creates a new one. - - -```ts -function upsert( - collection: string, - key: string | null, - text: string, - labels: string[] = [], - namespace: string = "", -): CollectionMutationResult -``` - - - Name of the collection, as [defined in the - manifest](/modus/app-manifest#collections). - - - - The unique identifier for the item in the namespace. If `null`, the function - generates a unique identifier. - - - - The text of the item to add to the collection. - - - - An optional array of labels to associate with the item. - - - - Associates the item with a specific namespace. Defaults to an empty namespace - if not provided. - - -#### upsertBatch - -Inserts or updates a batch of items into a collection. - - - If an item with the same key already exists, the original text is overwritten - with the new text. - - -```ts -function upsertBatch( - collection: string, - keys: string[] | null, - texts: string[], - labelsArr: string[][] = [], - namespace: string = "", -): CollectionMutationResult -``` - - - Name of the collection, as [defined in the - manifest](/modus/app-manifest#collections). - - - - Array of keys for the item to add to the collection. If you pass `null` for - any key, Hypermode assigns a new UUID as the key for the item. - - - - Array of texts for the items to add to the collection. - - - - An optional array of arrays of labels to associate with the items. - - - - Associates the item with a specific namespace. Defaults to an empty namespace - if not provided. - - -#### remove - -Removes an item from the collection. - -```ts -function remove( - collection: string, - key: string, - namespace: string = "", -): CollectionMutationResult -``` - - - Name of the collection, as [defined in the - manifest](/modus/app-manifest#collections). - - - - The key of the item to delete from the collection. - - - - The namespace to remove the item from. Defaults to the default namespace if - not provided. - - -### Search and Retrieval Functions - -#### computeDistance - -Computes distance between two keys in a collection using a search method's -embedder. - -```ts -function computeDistance( - collection: string, - searchMethod: string, - key1: string, - key2: string, - namespace: string = "", -): CollectionSearchResultObject -``` - - - Name of the collection, as [defined in the - manifest](/modus/app-manifest#collections). - - - - The search method used to calculate embedding for key's texts. - - - - Keys to compute similarity on. - - - - The namespace to search the items from. Defaults to the default namespace if - not provided. - - -#### getLabels - -Get the labels for an item in a collection. - -```ts -function getLabels( - collection: string, - key: string, - namespace: string = "", -): string[] -``` - - - Name of the collection, as [defined in the - manifest](/modus/app-manifest#collections). - - - - The key of the item to retrieve. - - - - The namespace to get the item from. Defaults to the default namespace if not - provided. - - -#### getNamespaces - -Get all namespaces in a collection. - -```ts -function getNamespaces(collection: string): string[] -``` - - - Name of the collection, as [defined in the - manifest](/modus/app-manifest#collections). - - -#### getText - -Gets an item's text from a collection, give the item's key. - -```ts -function getText( - collection: string, - key: string, - namespace: string = "", -): string -``` - - - Name of the collection, as [defined in the - manifest](/modus/app-manifest#collections). - - - - The key of the item to retrieve. - - - - The namespace to get the item from. Defaults to the default namespace if not - provided. - - -#### getTexts - -Get all items from a collection. The result is a map of key to text for all -items in the collection. - -```ts -function getTexts( - collection: string, - namespace: string = "", -): Map -``` - - - Name of the collection, as [defined in the - manifest](/modus/app-manifest#collections). - - - - The namespace to get the items from. Defaults to the default namespace if not - provided. - - -#### getVector - -Get the vector for an item in a collection. - -```ts -function getVector( - collection: string, - searchMethod: string, - key: string, - namespace: string = "", -): f32[] -``` - - - Name of the collection, as [defined in the - manifest](/modus/app-manifest#collections). - - - - The search method used to calculate embedding for key's texts. - - - - The key of the item to retrieve. - - - - The namespace to get the item from. Defaults to the default namespace if not - provided. - - -#### nnClassify - -Classify an item in the collection using previous vectors' labels. - -```ts -function nnClassify( - collection: string, - searchMethod: string, - text: string, - namespace: string = "", -): CollectionClassificationResult -``` - - - Name of the collection, as [defined in the - manifest](/modus/app-manifest#collections). - - - - The search method used to calculate embedding for text & search against. - - - - The text to compute natural language search on. - - - - The namespace to search the items from. Defaults to the default namespace if - not provided. - - -#### search - -Perform a natural language search on items within a collection. This method is -useful for finding items that match a search query based on semantic meaning. - - - Modus uses the same embedder for both inserting text into the collection, and - for the text used when searching the collection. - - -```ts -function search( - collection: string, - searchMethod: string, - text: string, - limit: i32, - returnText: bool = false, - namespaces: string[] = [], -): CollectionSearchResult -``` - - - Name of the collection, as [defined in the - manifest](/modus/app-manifest#collections). - - - - The search method used to calculate embedding for text & search against. - - - - The text to compute natural language search on. - - - - The number of result objects to return. - - - - A flag to return the texts in the response. - - - - A list of namespaces to search the item from. Defaults to the default - namespace if not provided. - - -#### searchByVector - -Perform a vector-based search on a collection, which is helpful for scenarios -requiring precise similarity calculations between pre-computed embeddings. - - - Modus uses the same embedder for both inserting text into the collection, and - for the vector used when searching the collection. - - -```ts -function searchByVector( - collection: string, - searchMethod: string, - vector: f32[], - limit: i32, - returnText: bool = false, - namespaces: string[] = [], -): CollectionSearchResult -``` - - - Name of the collection, as [defined in the - manifest](/modus/app-manifest#collections). - - - - The search method used to calculate embedding for vector & search against. - - - - The vector to compute search on. - - - - The number of result objects to return. - - - - A flag to return the texts in the response. - - - - An optional array of namespaces to search within. - - -### Maintenance Functions - -#### recomputeSearchMethod - -Recalculates the embeddings for all items in a collection. It can be -resource-intensive, use it when necessary, for example after you have updated -the method for embedding calculation and want to re-compute the embeddings for -existing data in the collection. - -```ts -function recomputeSearchMethod( - collection: string, - searchMethod: string, - namespace: string = "", -): SearchMethodMutationResult -``` - - - Name of the collection, as [defined in the - manifest](/modus/app-manifest#collections). - - - - The search method to recompute embeddings for. - - - - The namespace to use. Defaults to the default namespace if not provided. - - -### Types - -#### CollectionMutationResult - -Represents the result of a mutation operation on a collection. - -```ts -class CollectionMutationResult { - collection: string - status: CollectionStatus - error: string - isSuccessful: bool - operation: string - keys: string[] -} -``` - - - Name of the collection. - - - - The status of the operation. - - - - Error message, if any. - - - - A boolean indicating whether the operation completed successfully. Use this to - confirm success before handling the result. - - - - The operation performed. - - - - The keys of the items affected by the operation. - - -#### CollectionClassificationLabelObject - -Represents a classification label. - -```ts -class CollectionClassificationLabelObject { - label: string - confidence: f64 -} -``` - - - The classification label. - - - - The confidence score of the classification label. - - -#### CollectionClassificationResult - -Represents the result of a classification operation on a collection. - -```ts -class CollectionClassificationResult { - collection: string - status: CollectionStatus - error: string - isSuccessful: bool - searchMethod: string - labelsResult: CollectionClassificationLabelObject[] - cluster: CollectionClassificationResultObject[] -} -``` - - - Name of the collection. - - - - The status of the operation. - - - - Error message, if any. - - - - A boolean indicating whether the operation completed successfully. Use this to - confirm success before handling the result. - - - - The search method used in the operation. - - - - The classification labels. - - - - The classification results. - - -#### CollectionClassificationResultObject - -Represents an object in the classification results. - -```ts -class CollectionClassificationResultObject { - key: string - labels: string[] - distance: f64 - score: f64 -} -``` - - - The key of the item classified. - - - - The classification labels. - - - - The distance of the item from the classification labels. - - - - The similarity score of the item classified. - - -#### CollectionSearchResult - -Represents the result of a search operation on a collection. - -```ts -class CollectionSearchResult { - collection: string - status: CollectionStatus - error: string - isSuccessful: bool - searchMethod: string - objects: CollectionSearchResultObject[] -} -``` - - - Name of the collection. - - - - The status of the operation. - - - - Error message, if any. - - - - A boolean indicating whether the operation completed successfully. Use this to - confirm success before handling the result. - - - - The search method used in the operation. - - - - The search results. - - -#### CollectionSearchResultObject - -Represents an object in the search results. - -```ts -class CollectionSearchResultObject { - namespace: string - key: string - text: string - labels: string[] - distance: f64 - score: f64 -} -``` - - - The namespace of the item found as part of the search. - - - - The key of the item found as part of the search. - - - - The text of the item found as part of the search. - - - - The distance of the item from the search text. - - - - The similarity score of the item found, as it pertains to the search. - - -#### CollectionStatus - -The status of a collection operation. - -```ts -enum CollectionStatus { - Success = "success" - Error = "error" -} -``` - - - The operation was successful. - - - - The operation encountered an error. - - -#### SearchMethodMutationResult - -Represents the result of a mutation operation on a search method. - -```ts -class SearchMethodMutationResult { - collection: string - status: CollectionStatus - error: string - isSuccessful: bool - operation: string - searchMethod: string -} -``` - - - Name of the collection. - - - - The status of the operation. - - - - Error message, if any. - - - - A boolean indicating whether the operation completed successfully. Use this to - confirm success before handling the result. - - - - The operation performed. - - - - The search method affected by the operation. - diff --git a/modus/sdk/assemblyscript/overview.mdx b/modus/sdk/assemblyscript/overview.mdx index 383d26bb..832a1ff8 100644 --- a/modus/sdk/assemblyscript/overview.mdx +++ b/modus/sdk/assemblyscript/overview.mdx @@ -51,12 +51,6 @@ APIs. | :------------------- | :--------------------------------------------------------------------------------------------- | | [`models`](./models) | Invoke AI models, including large language models, embedding models, and classification models | -### Storage APIs - -| Namespace | Purpose | -| :----------------------------- | :--------------------------------------------------------- | -| [`collections`](./collections) | Provides integrated storage and vector search capabilities | - ### System APIs | Namespace | Purpose | diff --git a/modus/sdk/go/collections.mdx b/modus/sdk/go/collections.mdx deleted file mode 100644 index 0da91fc4..00000000 --- a/modus/sdk/go/collections.mdx +++ /dev/null @@ -1,718 +0,0 @@ ---- -title: "Collections APIs" -sidebarTitle: "Collections" -description: "Add storage and vector search capabilities to your functions." -icon: "circle-small" -iconType: "solid" ---- - -import { SdkHeader } from "/snippets/sdk-header.mdx" -import SdkTip from "/snippets/sdk-tip.mdx" - - - -The Modus Collection APIs allow you to add vector search within your functions. - -## Import - -To begin, import the `collections` package from the SDK: - -```go -import "github.com/hypermodeinc/modus/sdk/go/pkg/collections" -``` - -## Collections APIs - -{/* vale Google.Headings = NO */} - -The APIs in the `collections` package are below, organized by category. - - - -### Mutation Functions - -#### Upsert - -Inserts or updates an item in a collection. - - - If the item already exists, the function overwrites the previous value. If - not, it creates a new one. - - -```go -func Upsert( - collection string, - key *string, - text string, - labels []string, - opts ...NamespaceOption -) (*CollectionMutationResult, error) -``` - - - Name of the collection, as [defined in the - manifest](/modus/app-manifest#collections). - - - - The unique identifier for the item in the namespace. If `nil`, the function - generates a unique identifier. - - - - The text of the item to add to the collection. - - - - An optional slice of labels to associate with the item. - - - - Associates the item with a specific namespace. Defaults to an empty namespace - if not provided. - -Pass `collections.WithNamespace("namespace")` to specify a namespace. - - - -#### UpsertBatch - -Inserts or updates a batch of items into a collection. - - - If an item with the same key already exists, the original text is overwritten - with the new text. - - -```go -func UpsertBatch( - collection string, - keys []string, - texts []string, - labelsArr [][]string, - opts ...NamespaceOption -) (*CollectionMutationResult, error) -``` - - - Name of the collection, as [defined in the - manifest](/modus/app-manifest#collections). - - - - Slice of keys for the item to add to the collection. If you pass `nil` for any - key, Hypermode assigns a new UUID as the key for the item. - - - - Slice of texts for the items to add to the collection. - - - - An optional slice of slices of labels to associate with the items. - - - - Associates the item with a specific namespace. Defaults to an empty namespace - if not provided. - -Pass `collections.WithNamespace("namespace")` to specify a namespace. - - - -#### Remove - -Removes an item from the collection. - -```go -func Remove( - collection string, - key string, - opts ...NamespaceOption -) (*CollectionMutationResult, error) -``` - - - Name of the collection, as [defined in the - manifest](/modus/app-manifest#collections). - - - - The key of the item to delete from the collection. - - - - The namespace to remove the item from. Defaults to the default namespace if - not provided. - -Pass `collections.WithNamespace("namespace")` to specify a namespace. - - - -### Search and Retrieval Functions - -#### ComputeDistance - -Computes distance between two keys in a collection using a search method's -embedder. - -```go -func ComputeDistance( - collection string, - searchMethod string, - key1 string, - key2 string, - opts ...NamespaceOption -) (*CollectionSearchResultObject, error) -``` - - - Name of the collection, as [defined in the - manifest](/modus/app-manifest#collections). - - - - The search method used to calculate embedding for key's texts. - - - - Keys to compute similarity on. - - - - The namespace to search the items from. Defaults to the default namespace if - not provided. - -Pass `collections.WithNamespace("namespace")` to specify a namespace. - - - -#### NnClassify - -Classify an item in the collection using previous vectors' labels. - -```go -func NnClassify( - collection string, - searchMethod string, - text string, - opts ...NamespaceOption -) (*CollectionClassificationResult, error) -``` - - - Name of the collection, as [defined in the - manifest](/modus/app-manifest#collections). - - - - The search method used to calculate embedding for text & search against. - - - - The text to compute natural language search on. - - - - The namespace to search the items from. Defaults to the default namespace if - not provided. - -Pass `collections.WithNamespace("namespace")` to specify a namespace. - - - -#### GetLabels - -Get the labels for an item in a collection. - -```go -func GetLabels( - collection string, - key string, - opts ...NamespaceOption -) ([]string, error) -``` - - - Name of the collection, as [defined in the - manifest](/modus/app-manifest#collections). - - - - The key of the item to retrieve. - - - - The namespace to get the item from. Defaults to the default namespace if not - provided. - -Pass `collections.WithNamespace("namespace")` to specify a namespace. - - - -#### GetNamespaces - -Get all namespaces in a collection. - -```go -func GetNamespaces(collection string) ([]string, error) -``` - - - Name of the collection, as [defined in the - manifest](/modus/app-manifest#collections). - - -#### GetText - -Gets an item's text from a collection, give the item's key. - -```go -func GetText( - collection string, - key string, - opts ...NamespaceOption -) (string, error) -``` - - - Name of the collection, as [defined in the - manifest](/modus/app-manifest#collections). - - - - The key of the item to retrieve. - - - - The namespace to get the item from. Defaults to the default namespace if not - provided. - -Pass `collections.WithNamespace("namespace")` to specify a namespace. - - - -#### GetTexts - -Get all items from a collection. The result is a map of key to text for all -items in the collection. - -```go -func GetTexts( - collection string, - opts ...NamespaceOption -) (map[string]string, error) -``` - - - Name of the collection, as [defined in the - manifest](/modus/app-manifest#collections). - - - - The namespace to get the items from. Defaults to the default namespace if not - provided. - -Pass `collections.WithNamespace("namespace")` to specify a namespace. - - - -#### GetVector - -Get the vector for an item in a collection. - -```go -func GetVector( - collection string, - searchMethod string, - key string, - opts ...NamespaceOption -) ([]float32, error) -``` - - - Name of the collection, as [defined in the - manifest](/modus/app-manifest#collections). - - - - The search method used to calculate embedding for key's texts. - - - - The key of the item to retrieve. - - - - The namespace to get the item from. Defaults to the default namespace if not - provided. - -Pass `collections.WithNamespace("namespace")` to specify a namespace. - - - -#### Search - -Perform a natural language search on items within a collection. This method is -useful for finding items that match a search query based on semantic meaning. - - - Modus uses the same embedder for both inserting text into the collection, and - for the text used when searching the collection. - - -```go -func Search( - collection string, - searchMethod string, - text string, - opts ...SearchOption -) (*CollectionSearchResult, error) -``` - - - Name of the collection, as [defined in the - manifest](/modus/app-manifest#collections). - - - - The search method used to calculate embedding for text & search against. - - - - The text to compute natural language search on. - - - - Additional options for the search: - -- `collections.WithLimit(limit int)`: The number of result objects to return. -- `collections.WithReturnText(returnText bool)`: A flag to return the texts in - the response. -- `collections.WithNamespaces(namespaces []string)`: A list of namespaces to - search the item from. Defaults to the default namespace if not provided. - - - -#### SearchByVector - -Perform a vector-based search on a collection, which is helpful for scenarios -requiring precise similarity calculations between pre-computed embeddings. - - - Modus uses the same embedder for both inserting text into the collection, and - for the vector used when searching the collection. - - -```go -func SearchByVector( - collection string, - searchMethod string, - vector []float32, - opts ...SearchOption -) (*CollectionSearchResult, error) -``` - - - Name of the collection, as [defined in the - manifest](/modus/app-manifest#collections). - - - - The search method used to calculate embedding for vector & search against. - - - - The vector to compute search on. - - - - Additional options for the search: - -- `collections.WithLimit(limit int)`: The number of result objects to return. -- `collections.WithReturnText(returnText bool)`: A flag to return the texts in - the response. -- `collections.WithNamespaces(namespaces []string)`: A list of namespaces to - search the item from. Defaults to the default namespace if not provided. - - - -### Maintenance Functions - -#### RecomputeSearchMethod - -Recalculates the embeddings for all items in a collection. It can be -resource-intensive, use it when necessary, for example after you have updated -the method for embedding calculation and want to re-compute the embeddings for -existing data in the collection. - -```go -func RecomputeSearchMethod( - collection string, - searchMethod string, - opts ...NamespaceOption -) (*SearchMethodMutationResult, error) -``` - - - Name of the collection, as [defined in the - manifest](/modus/app-manifest#collections). - - - - The search method to recompute embeddings for. - - - - The namespace to use. Defaults to the default namespace if not provided. - -Pass `collections.WithNamespace("namespace")` to specify a namespace. - - - -### Types - -#### CollectionClassificationLabelObject - -Represents a classification label. - -```go -type CollectionClassificationLabelObject struct { - Label string - Confidence float64 -} -``` - - - The classification label. - - - - The confidence score of the classification label. - - -#### CollectionClassificationResult - -Represents the result of a classification operation on a collection. - -```go -type CollectionClassificationResult struct { - Collection string - Status string - Error string - SearchMethod string - LabelsResult []*CollectionClassificationLabelObject - Cluster []*CollectionClassificationResultObject -} -``` - - - Name of the collection. - - - - The status of the operation. - - - - Error message, if any. - - - - The search method used in the operation. - - - - The classification labels. - - - - The classification results. - - -#### CollectionClassificationResultObject - -Represents an object in the classification results. - -```go -type CollectionClassificationResultObject struct { - Key string - Labels []string - Distance float64 - Score float64 -} -``` - - - The key of the item classified. - - - - The classification labels. - - - - The distance of the item from the classification labels. - - - - The similarity score of the item classified. - - -#### CollectionMutationResult - -Represents the result of a mutation operation on a collection. - -```go -type CollectionMutationResult struct { - Collection string - Status string - Error string - Operation string - Keys []string -} -``` - - - Name of the collection. - - - - The status of the operation. - - - - Error message, if any. - - - - The operation performed. - - - - The keys of the items affected by the operation. - - -#### CollectionSearchResult - -Represents the result of a search operation on a collection. - -```go -type CollectionSearchResult struct { - Collection string - Status string - Error string - SearchMethod string - Objects []*CollectionSearchResultObject -} -``` - - - Name of the collection. - - - - The status of the operation. - - - - Error message, if any. - - - - The search method used in the operation. - - - - The search results. - - -#### CollectionSearchResultObject - -Represents an object in the search results. - -```go -type CollectionSearchResultObject struct { - Namespace string - Key string - Text string - Labels []string - Distance float64 - Score float64 -} -``` - - - The namespace of the item found as part of the search. - - - - The key of the item found as part of the search. - - - - The text of the item found as part of the search. - - - - The distance of the item from the search text. - - - - The similarity score of the item found, as it pertains to the search. - - -#### CollectionStatus - -The status of a collection operation. - -```go -type CollectionStatus = string - -const ( - Success CollectionStatus = "success" - Error CollectionStatus = "error" -) -``` - -The operation was successful. - -The operation encountered an error. - -#### SearchMethodMutationResult - -Represents the result of a mutation operation on a search method. - -```go -type SearchMethodMutationResult struct { - Collection string - Status string - Error string - Operation string - SearchMethod string -} -``` - - - Name of the collection. - - - - The status of the operation. - - - - Error message, if any. - - - - The operation performed. - - - - The search method affected by the operation. - diff --git a/modus/sdk/go/overview.mdx b/modus/sdk/go/overview.mdx index f0a78e65..1701ac6b 100644 --- a/modus/sdk/go/overview.mdx +++ b/modus/sdk/go/overview.mdx @@ -49,12 +49,6 @@ your convenience. Click on a package to view more information about its APIs. | :------------------- | :--------------------------------------------------------------------------------------------- | | [`models`](./models) | Invoke AI models, including large language models, embedding models, and classification models | -### Storage APIs - -| Package | Purpose | -| :----------------------------- | :--------------------------------------------------------- | -| [`collections`](./collections) | Provides integrated storage and vector search capabilities | - ### System APIs | Package | Purpose | diff --git a/modus/search.mdx b/modus/search.mdx deleted file mode 100644 index 21ec039c..00000000 --- a/modus/search.mdx +++ /dev/null @@ -1,467 +0,0 @@ ---- -title: Search -description: "Add natural language search to your app using AI embeddings" -"og:title": "Search - Modus" ---- - -The Modus Collections API provides a robust way to store, retrieve, and search -through data using both natural language and vector-based search methods. By -leveraging embeddings, developers can enable semantic and similarity-based -searches, improving the relevance of search results within their apps. - -For example, with natural language similarity, if you search for a product -description like 'sleek red sports car', the search method returns similar -product descriptions such as "luxury sports car in red" or 'high-speed car with -sleek design'. - -## Understanding key components - -**Collections**: a collection is a structured storage that organizes and stores -textual data and associated metadata. Collections enable sophisticated search, -retrieval, and classification tasks using vector embeddings. - -**Search Methods**: a search method associated with a collection, defines how to -convert collection items into a vector representation and provides indexing -parameters. - -**Vector embeddings**: for vector-based search and comparison, Modus converts -each item in the collection into a vector representation called **embedding**. -By embedding data, you enable powerful natural language and similarity-based -searches. - - - Modus runtime automatically compute the embeddings, according to your - configuration, when you add or update items. - - -## Initializing your collection - -Before implementing search, ensure you have -[defined a collection in the app manifest](./app-manifest#collections). In this -example, `myProducts` is the collection used to store product descriptions. - -First, we need to populate the collection with items (for example, product -descriptions). You can insert individual or multiple items using the `upsert` -and `upsertBatch` methods, respectively. - -Use `upsert` to insert a product description into the collection. If you don't -specify a key, Modus generates a unique key for you. - - - -```go Go -func AddProduct(description string) ([]string, error) { - res, err := collections.Upsert( - "myProducts", // Collection name defined in the manifest - nil, // using nil to let Modus generate a unique ID - description, // the text to store - nil // we don't have labels for this item - ) - if err != nil { - return nil, err - } - return res.Keys, nil -} -``` - -```ts AssemblyScript -export function addProduct(description: string): string { - const response = collections.upsert( - "myProducts", // Collection name defined in the manifest - null, // using null to let Modus generate a unique ID - description, // the text to store - // no labels for this item - // no namespace provided, use defautl namespace - ) - return response.keys[0] // return the identifier of the item -} -``` - - - -## Configure your search method - -The search capability relies on a search method and embedding function. To -configure your search method. - -### Create an embedding function - -An embedding function is any API function that transforms text into vectors that -represent their meaning in a high-dimensional space. - -Embeddings functions must have the following signature: - - - -```go Go -package main - -func Embed(text []string) ([][]float32, error) { - ... -} - -``` - -```ts AssemblyScript -export function embed(text: string[]): f32[][] { - ... -} -``` - - - -Modus computes vectors using embedding models. Here are a few examples: - - - - -[Declare the model](./app-manifest#models) in the app manifest - -```json model.json - "models": { - // model card: https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2 - "minilm": { - "sourceModel": "sentence-transformers/all-MiniLM-L6-v2", // model name on the provider - "provider": "hugging-face", // provider for this model - "connection": "hypermode" // host where the model is running - } - } -``` - -Create the embedding function using the embedding model: - - - -```go Go -package main - -import ( - "github.com/hypermodeinc/modus/sdk/go/models" - "github.com/hypermodeinc/modus/sdk/go/models/experimental" -) - -func Embed(text []string) ([][]float32, error) { - // "minilm" is the model name declared in the app manifest - model, err := models.GetModel[experimental.EmbeddingsModel]("minilm") - if err != nil { - return nil, err - } - - input, err := model.CreateInput(text...) - if err != nil { - return nil, err - } - output, err := model.Invoke(input) - if err != nil { - return nil, err - } - return output.Predictions, nil -} - -``` - -```ts AssemblyScript -import { models } from "@hypermode/modus-sdk-as" -import { EmbeddingsModel } from "@hypermode/modus-sdk-as/models/experimental/embeddings" - -export function embed(texts: string[]): f32[][] { - // "minilm" is the model name declared in the app manifest - const model = models.getModel("minilm") - const input = model.createInput(texts) - const output = model.invoke(input) - return output.predictions -} -``` - - - - - [Declare the model](./app-manifest#models) in the app manifest - -```json modus.json - "models": { - // model docs: https://platform.openai.com/docs/models/embeddings - "openai-embeddings": { - "sourceModel": "text-embedding-3-small", - "connection": "openai", - "path": "v1/embeddings" - } - }, - "connections": { - "openai": { - "type": "http", - "baseUrl": "https://api.openai.com/", - "headers": { - "Authorization": "Bearer {{API_KEY}}" - } - } - } -``` - -Create the embedding function using the embedding model: - - - -```go Go -import ( - "github.com/hypermodeinc/modus/sdk/go/models" - "github.com/hypermodeinc/modus/sdk/go/models/experimental" -) - -func Embed(texts ...string) ([][]float32, error) { - // retrieve the model for OpenAI embeddings - // "openai-embeddings" is the model name declared in the app manifest - model, err := models.GetModel[openai.EmbeddingsModel]("openai-embeddings") - if err != nil { - return nil, fmt.Errorf("failed to get OpenAI embeddings model: %w", err) - } - - // create input for the model using the provided texts - input, err := model.CreateInput(texts) - if err != nil { - return nil, fmt.Errorf("failed to create input for OpenAI embeddings: %w", err) - } - - // invoke the model with the generated input - output, err := model.Invoke(input) - if err != nil { - return nil, fmt.Errorf("failed to invoke OpenAI embeddings model: %w", err) - } - - // prepare the result slice based on the size of the output data - results := make([][]float32, len(output.Data)) - - // copy embeddings from output into the result slice - for i, d := range output.Data { - results[i] = d.Embedding - } - - return results, nil -} -``` - -```ts AssemblyScript -export function embed(text: string[]): f32[][] { - const model = models.getModel("openai-embeddings") - // "openai-embeddings" is the model name declared in the app manifest - const input = model.createInput(text) - const output = model.invoke(input) - return output.data.map((d) => d.embedding) -} -``` - - - - - -### Declare the search method - -With an embedding function in place, declare a search method in the -[collection properties](/modus/app-manifest#collections). - -```json modus.json - "collections": { - "myProducts": { - "searchMethods": { - "searchMethod1": { - "embedder": "embed" // embedding function name - } - } - } - } - -``` - -## Implement semantic similarity search - -With the products stored, you can now search the collection by semantic -similarity. The search] API computes an embedding for the provided text, -compares it with the embeddings of the items in the collection, and returns the -most similar items. - - - -```go Go -func SearchProducts(productDescription string, maxItems int) (*collections.CollectionSearchResult, error) { - return collections.Search(myProducts, searchMethods[0], productDescription, collections.WithLimit(maxItems), collections.WithReturnText(true)) -} -``` - -```ts AssemblyScript -export function searchProducts( - product_description: string, - maxItems: i32, -): collections.CollectionSearchResult { - const response = collections.search( - "myProducts", // collection name declared in the app manifest - "searchMethod1", // search method declared for this collection in the manifest - product_description, // text to search for - maxItems, - true, // returnText: bool, true to return the items text. - // no namespace provide, use the default namespace - ) - return response -} -``` - - - -### Search result format - -The search response is a CollectionSearchResult containing the following fields: - -- `collection`: the name of the collection. -- `status`: the status of the operation. -- `objects`: the search result items with their text, distance, and score - values. - - `distance`: a lower value indicates a closer match between the search query - and the item in the collection - - `score`: a higher value (closer to 1) represents a better match - -```json -{ - "collection": "myProducts", - "status": "success", - "objects": [ - { - "key": "item-key-123", - "text": "Sample product description", - "distance": 0.05, - "score": 0.95 - } - ] -} -``` - -## Search for similar Items - -When you need to search similar items to a given item, use the `searchByVector` -API. Retrieve the vector associated with the given item by its key, then perform -a search using that vector. - - - -```go Go -func SearchSimilarProduct(productKey string, maxItems int) (*collections.CollectionSearchResult, error) { - vec, err := collections.GetVector( - "myProducts", - "searchMethod1", - productKey) - - if err != nil { - return nil, err - } - return collections.SearchByVector( - "myProducts", - "searchMethod1", - vec, - collections.WithLimit(maxItems), - collections.WithReturnText(true) - ) -} -``` - -```ts AssemblyScript -export function searchSimilarProducts( - productId: string, - maxItems: i32, -): collections.CollectionSearchResult { - const embedding_vector = collections.getVector( - "myProducts", // Collection name defined in the manifest - "searchMethod1", // search method declared for the collection - productId, // key of the collection item to retrieve - ) - // search for similar products using the embedding vector - const response = collections.searchByVector( - "myProducts", - "searchMethod1", - embedding_vector, - maxItems, - true, // get the product description - ) - - return response -} -``` - - - -## Develop locally with Collections - -While Collections expose a key-value interface for working with data, a -PostgreSQL database instance persists the data. When using Collections in a -Modus app deployed to the Hypermode platform, Hypermode manages this PostgreSQL -database and users don't need to perform any additional setup. However, when -developing with Modus locally or outside of the Hypermode platform, you need a -PostgreSQL instance for the Collections persistence layer. - - - The dependency on PostgreSQL is temporary and we're working to replace it with - ModusDB, an embedded multi-model database, in an upcoming release. - - -Any hosting method for this PostgreSQL database is sufficient, so feel free to -use your favorite method of installing and running PostgreSQL locally or in the -cloud. You must apply a database migration after you start the PostgreSQL -database (Step 3 below) and set the `MODUS_DB` environment variable with your -PostgreSQL database connection string (Step 4 below). The steps below describe -using [Docker](https://www.docker.com/products/docker-desktop/) to start and -configure a PostgreSQL instance for local development with Collections. - -To start and configure a local PostgreSQL instance for working with Collections -locally using [Docker Compose](https://docs.docker.com/compose/), follow these -steps: - - - - - Clone the [Modus GitHub repository](https://github.com/hypermodeinc/modus): - -```sh -git clone https://github.com/hypermodeinc/modus.git -``` - - - - - -Start the Collections PostgreSQL database using the local Docker Compose script: - -```sh -cd modus/runtime/tools/local -docker compose up -``` - - - - - -Next, apply the database schema using the -[golang-migrate](https://github.com/golang-migrate/migrate) utility. - -On MacOS, you can install this utility with the following: - -```sh -brew install golang-migrate -``` - -Then, you can apply the migration as follows: - -```sh -export POSTGRESQL_URL='postgresql://postgres:postgres@localhost:5433/my-runtime-db?sslmode=disable' -migrate -database ${POSTGRESQL_URL} -path ../../db/migrations up -``` - - - - - Set the `MODUS_DB` environment variable: - -```sh -export MODUS_DB=postgresql://postgres:postgres@localhost:5433/my-runtime-db?sslmode=disable -``` - - - - -You can now use Collections locally in your Modus app.