Metadata-Version: 2.4
Name: torque-http
Version: 0.5.0
Summary: Official Python client for Torque — Truespar's in-memory search engine with a Typesense v30.1 compatible API. Zero external dependencies.
Project-URL: Homepage, https://truespar.com/torque/docs
Project-URL: Documentation, https://truespar.com/torque/docs
Author: Truespar
License-Expression: MIT
License-File: LICENSE
Keywords: search,torque,truespar,typesense,vector-search
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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: Topic :: Database :: Front-Ends
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# torque-http

Official Python client for [Torque](https://truespar.com/torque/docs) — Truespar's in-memory search engine with a Typesense v30.1 compatible API.

- **Zero external dependencies** — uses only the Python standard library
- **HTTP API** for search, collection management, and document CRUD
- **TCP binary ingest** for high-throughput streaming from databases
- **TQBF file upload** for bulk import
- Multi-node failover with automatic retry
- Typed search parameters and response models
- Python 3.10+, MIT licensed

## Installation

```bash
pip install torque-http
```

## Quick Start

```python
from torque_http import TorqueHttpClient, SearchParameters

client = TorqueHttpClient("http://localhost:8108", api_key="your-key")

# Search
results = client.search("products", q="laptop", query_by="title")
for hit in results.hits:
    print(hit.document["title"])

# Typed parameters
params = SearchParameters(
    q="laptop",
    query_by="title,description",
    filter_by="price:>100",
    per_page=20,
)
results = client.search("products", params)
```

## Multi-node with failover

```python
client = TorqueHttpClient(
    ["http://node1:8108", "http://node2:8108"],
    api_key="your-key",
    num_retries=5,
)
```

## Collection management

```python
schema = {
    "name": "products",
    "fields": [
        {"name": "title", "type": "string"},
        {"name": "price", "type": "float", "sort": True},
        {"name": "brand", "type": "string", "facet": True},
    ],
}
client.create_collection(schema)

client.create_document("products", {
    "id": "1", "title": "Laptop Pro", "price": 1299.99, "brand": "Acme",
})
```

## High-throughput TCP ingest

For streaming 100K+ documents, use the binary TCP protocol:

```python
from torque_http import TorqueIngestClient, DocumentEncoder

schema = {"fields": [
    {"name": "title", "type": "string"},
    {"name": "price", "type": "float"},
]}
encoder = DocumentEncoder(schema)

with TorqueIngestClient() as tcp:
    tcp.connect("localhost", 8109)
    tcp.start_ingest("products")
    tcp.send_batch(documents, encoder)
    tcp.commit()
```

## TQBF bulk file import

Pre-encode a compressed binary file for maximum throughput:

```python
from torque_http import TorqueBinaryFileWriter, DocumentEncoder

encoder = DocumentEncoder(schema)
with TorqueBinaryFileWriter("data.tqbf", encoder) as writer:
    for doc in source:
        writer.write(doc)

client.import_binary("products", "data.tqbf")
```

## Documentation

- [Torque documentation](https://truespar.com/torque/docs)

## License

MIT — see [LICENSE](LICENSE).
