Metadata-Version: 2.1
Name: upstash-search
Version: 0.1.1
Summary: An HTTP/REST based AI Search client built on top of Upstash REST API.
Home-page: https://github.com/upstash/search-py
License: MIT
Keywords: Search,Upstash Search,Serverless Search
Author: Upstash
Author-email: support@upstash.com
Maintainer: Upstash
Maintainer-email: support@upstash.com
Requires-Python: >=3.9,<4.0
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Database
Classifier: Topic :: Database :: Front-Ends
Classifier: Topic :: Software Development :: Libraries
Requires-Dist: httpx (>=0.23.0,<1)
Project-URL: Repository, https://github.com/upstash/search-py
Description-Content-Type: text/markdown

# Upstash AI Search Python Client

> [!NOTE]
> **This project is in GA Stage.**
>
> The Upstash Professional Support fully covers this project. It receives regular updates, and bug fixes.
> The Upstash team is committed to maintaining and improving its functionality.

It is a connectionless (HTTP based) AI Search client and designed for:

- Serverless functions (AWS Lambda ...)
- Cloudflare Workers
- Next.js, Jamstack ...
- Client side web/mobile applications
- WebAssembly
- and other environments where HTTP is preferred over TCP.

## Quick Start

### Install

#### Python

```bash
pip install upstash-search
```

### Create Database

Create a new database on [Upstash](https://console.upstash.com/search)

## Basic Usage:

```py
from upstash_search import Search

client = Search(
    url="<UPSTASH_SEARCH_REST_URL>",
    token="<UPSTASH_SEARCH_REST_TOKEN>",
)

# Access the index of a database
index = client.index("movies")

# Upsert documents into index
index.upsert(
    documents=[
        {
            "id": "movie-0",
            "content": {
                "title": "Star Wars",
                "overview": "Sci-fi space opera",
                "genre": "sci-fi",
                "category": "classic",
            },
            "metadata": {
                "poster": "https://poster.link/starwars.jpg",
            },
        },
        {
            "id": "movie-1",
            "content": {
                "title": "Inception",
                "overview": "Mind-bending thriller",
                "genre": "sci-fi",
                "category": "modern",
            },
            "metadata": {
                "poster": "https://poster.link/inception.jpg",
            },
        },
    ],
)

# Fetch documents by ids
documents = index.fetch(
    ids=["movie-0", "movie-1"],
)
print(documents)

# AI search
scores = index.search(
    query="space opera",
    limit=2,
)
print(scores)

# AI search with reranking
scores = index.search(
    query="space opera",
    limit=2,
    reranking=True
)
print(scores)

# AI search with only semantic search
scores = index.search(
  query="space opera",
  limit=2,
  semantic_weight=1
)

# AI search with only full-text search
scores = index.search(
  query="space opera",
  limit=2,
  semantic_weight=0
)

# AI search with full-text search and sematic search
# combined with equal weights
scores = index.search(
  query="space opera",
  limit=2,
  semantic_weight=0.5
)

# AI search without input enrichment
scores = index.search(
  query="space opera",
  limit=2,
  input_enrichment=False
)

# AI search with filtering
scores = index.search(
    query="space opera",
    limit=2,
    filter="category = 'classic'",
)
print(scores)

# Range over documents
range_documents = index.range(
    cursor="",
    limit=1,
)
print(range_documents.documents)

# Range over the next page of documents
range_documents = index.range(
    cursor=range_documents.next_cursor,
    limit=3,
)

# Delete a document by id
index.delete(
    ids=["movie-0"],
)

# Reset the index (delete all documents)
index.reset()

# Get database and index info
info = client.info()
print(info)
```

