raily-ai 0.5.0

Official Python SDK for the Raily search API.

Raily Python SDK

Official Python client for the Raily search API — search your own sources from your app with a typed, one-call client.

Documentation · Source

Install

pip install raily-ai

Quickstart

from raily import Raily

client = Raily(api_key="rly_...", endpoint="https://<your-endpoint-url>")

for hit in client.search("anti-aging serum", limit=5):
    print(hit.score, hit.fields.get("title"))

Async

from raily import AsyncRaily

client = AsyncRaily(api_key="rly_...", endpoint="https://<your-endpoint-url>")
hits = await client.search("anti-aging serum", limit=5)

Authentication

Create an API key in your Raily workspace (Identities → API keys) and pass it as api_key. The endpoint is your endpoint's URL. A key is scoped to one workspace and to the endpoint it was issued for — using it elsewhere is rejected.

import os
client = Raily(api_key=os.environ["RAILY_API_KEY"], endpoint=os.environ["RAILY_ENDPOINT"])

Results

search() returns a list of SearchHit:

field	type	meaning
score	float | None	relevance score
fields	dict[str, str]	flat {name: value} map of the source's display fields, e.g. hit.fields["title"]
text	str | None	a rendered text summary
image_url	str | None	the result's image, for image sources
is_relevant	bool | None	False for an exploratory (below-threshold) hit
source_collection	str | None	the source the hit came from
id	str | None	stable result id
raw	dict	the full original result, for anything not surfaced above

fields is a flat dict, so you read a value by name:

hit.fields["title"]              # e.g. "Anti-Aging Vitamin C Serum"
hit.fields.get("published_date") # None if this source doesn't expose it

The exact keys come from the source's configured display fields (e.g. title, author, published_date). Print one hit's fields to see what your source exposes.

Debugging empty results

A bare [] doesn't say why. Pass explain=True for the endpoint's message plus a hint:

res = client.search("articles", explain=True)
print(res.info.count, res.info.message, res.info.note)  # note is set only when empty

Most empty results are a too-generic query ("articles" matches nothing — search a topic), a freshness filter, or an unindexed corpus. Or construct with debug=True to log a hint on every empty result.

Errors

from raily import RailyError, RailyAuthError

try:
    client.search("query")
except RailyAuthError:
    ...  # key missing / invalid / expired / not authorized for this endpoint
except RailyError:
    ...  # everything else (network, server, protocol)

License

Apache-2.0