Integration

While you can use the Hyperspell API directly to query data, the most common way to query data is using the Hyperspell SDKs, which are available Python and TypeScript.

​

Installation

pip install hyperspell
# Or using Poetry
poetry add hyperspell
# Or using uv
uv add hyperspell

To initialize the client, you need to generate an app token in your dashboard.

from hyperspell import Hyperspell

client = Hyperspell(api_key="YOUR_APP_TOKEN")

You can also set the HYPERSPELL_API_KEY environment variable and omit the api_key parameter when initializing the client. An app token allows you to insert and query data for any user of your app. Please refer to the Generating Tokens section for more information on how to generate user tokens that are specific to a single user instead.

​

Usage

Before you can query data, you need to add a document. In this example, we’ll add a a simple poem. We’ll also tag this poem by adding it to the collection poems (if it doesn’t exist, it will be created automatically) — that lets us query for all poems later.

document_status = client.documents.add(
    text="’Twas brillig, and the slithy toves did gyre and gimble in the wabe...",
    collection="poems"
)
print(document_status.id)

The resource_id returned will be the ID of the document. You can use this ID to query the document later. Some types of documents may take several seconds to process, so you may need to wait for the document to be processed before you can query it.

Once you have added a document, you can query it using the query method.

response = client.query.search(
    query="what is a borogove?",
    sources=["collections"],
    options={
        "collections": {
            "collection": "poems"
        }
    }
)
print(response.documents)

As you can see, the query method takes a query string, and a sources parameter that lists the sources you want to query. In this example, we used collections as a source, which contains all documents added manually with the /documents/add endpoint.

Each data source comes with different options when querying data. In this example, we used the collections source, so in the options field we will find a key with the name of the source (collections) which contains all the options. In this case, we only have one option, which is the collection parameter. Note that if we didn’t set this parameter, all collections would be searched.

​

Asking questions about your data

By default, the query will return the most relevant documents (or parts of documents) that match the query. Documents contain both structured data that you can use ie. in your UI to show results, and an LLM-summary that you can use for retrieval-augmented generation.

Of course, you can also use Hyperspell to answer questions about your document directly. To do so, simply include the answer parameter in your query:

response = client.query.search(
    query="which attacks does the jabberwock have?",
    sources=["collections"],
    answer=True,
    options={
        "collections": {
            "collection": "poems"
        }
    }
)
print(response.answer)

​

Querying multiple sources

You can query multiple sources at once by passing a list of sources to the sources parameter.

response = client.query.search(
    query="what did joe think about my poetry collection?",
    sources=["slack", "gmail"]
)
print(response.documents)

In this example, we’re querying both the slack and gmail sources. Both sources are queried at the same time, and the results are merged together. You can use Hyperspell Connect to let your users securely connect their accounts to Hyperspell, and then query their data.