Railengine Retrieval SDK
Python SDK for retrieving and searching data from Railtown AI Railengine - handles embeddings, storage documents, and indexed content.
Overview
The rail-engine package provides a Pythonic interface for retrieving and searching data from Railengine. It supports async/await patterns, client-side filtering, explicit storage list paging via StorageListPage, and Pydantic model deserialization.
Installation
uv pip install rail-engine
Quick Start
import asyncio
from railtown.engine import Railengine
async def main():
# Initialize client (reads from ENGINE_PAT and ENGINE_ID env vars)
async with Railengine() as client:
page = await client.list_storage_documents(
page_number=1,
page_size=25,
)
print(f"total_count={page.total_count} total_pages={page.total_pages}")
for doc in page.items:
print(doc)
asyncio.run(main())
Configuration
Environment Variables
ENGINE_PAT(required) - Personal Access TokenENGINE_ID(required) - Engine ID (can also be passed to constructor)RAILTOWN_API_URL(optional) - Base API URL (defaults tohttps://cndr.railtown.ai/api)
Constructor Parameters
pat(optional) - PAT token (if not provided, reads fromENGINE_PATenv)engine_id(optional) - Engine ID (if not provided, reads fromENGINE_IDenv, required if not in env)api_url(optional) - Base API URL (if not provided, reads fromRAILTOWN_API_URLenv or defaults to production)model(optional) - Pydantic model type for deserializing retrieved datatimeout(optional) - Request timeout in seconds orhttpx.Timeout(default30). Applied to the SDK-created client and to each request, including vector search.verify(optional) - TLS verification. Defaults toTrue. Pass a CA bundle path orssl.SSLContextfor custom trust.Falsedisables verification and must be set explicitly.http_client(optional) - Caller-ownedhttpx.AsyncClientfor proxies, custom transports, or tests. The SDK does not close this client.retrieval_error_mode(optional) -"raise"(default) or"fallback"; see the error contract below.logging_policy(optional) -LoggingPolicyfor SDK logs. Default logs operation metadata only. Search text, JSONPath, and response bodies are not logged unlesslog_content=True.
Earlier SDK versions disabled TLS verification. 0.4.0 verifies certificates by default. Use verify= with your CA bundle if the API host uses a private certificate.
Features
- Multiple retrieval methods:
search_vector_store()- Semantic search in vector storessearch_vector_store_filtered()- Semantic search restricted to the documents an index query matches (search_querytakes the sameIndexingSearchQuery/dict assearch_index; requires Indexing and Embeddings enabled on the engine)get_storage_document_by_event_id()- Get document by EventIdget_storage_document_by_customer_key()- Same paging aslist_storage_documents(page_number,page_size) but scoped to a CustomerKey; returnsStorageListPagewithitems,total_pages, andtotal_countquery_storage_by_jsonpath()- Query using JSONPathlist_storage_documents()- Usepage_numberandpage_sizeto paginate; returnsStorageListPagewithitems,total_pages, andtotal_countsearch_index()- Index search (defaultraw=True: each hit is the API dict; useraw=Falseto parse each hit'sbodywithmodelor the client default); returnsIndexingSearchResultwithitemsand optionaltotal_countdelete_event()- Delete an event from storage, embeddings, and indexing (raises on API errors)
- Client-side filtering on storage reads - Optional
filter_fnon storage/list/query helpers (not onsearch_vector_storeorsearch_vector_store_filtered; filter vector hits in your loop) - Storage list pagination - One HTTP GET per page; use
page_number/page_sizeon the request andtotal_pages/total_countonStorageListPagewhen looping - Model deserialization - Optional Pydantic model support with per-call override
- Actionable error handling - Retrieval failures raise by default; explicit fallback mode supports legacy integrations
- Async/await support - Built for modern async Python applications
Error Handling
The SDK provides custom exception classes:
RailtownError- Base exceptionRailtownBadRequestError- 400 Bad RequestRailtownUnauthorizedError- 401 UnauthorizedRailtownNotFoundError- 404 Not FoundRailtownConflictError- 409 ConflictRailtownServerError- 5xx Server errors
Error contract and migration to 0.5.0
Version 0.5.0 changes retrieval failures to raise by default. Successful empty queries keep their existing result types and pagination metadata. To retain the previous retrieval fallback behavior, explicitly construct Railengine(retrieval_error_mode="fallback"). Fallback logs the failure and returns an empty list, empty result/page, or None for an event lookup. It does not suppress ingestion or deletion failures, invalid arguments, cancellation, or application callback errors. User-model validation and per-record deserialization fallback are unchanged.
A 404 raises RailtownNotFoundError by default, including event lookups. The current API contract does not establish a reliable discriminator between a missing document and another missing resource; the SDK does not infer which one is absent or perform another request to guess.
Catch the common base class for all request/response errors:
from railtown.engine import Railengine, RailtownError
async def search():
async with Railengine() as client:
try:
return await client.search_index(query={"search": "example"})
except RailtownError as error:
print(error.operation, error.status_code, error.request_id)
raise
HTTP 400, 401, 403, 404, 409, and 429 map to RailtownBadRequestError, RailtownUnauthorizedError, RailtownForbiddenError, RailtownNotFoundError, RailtownConflictError, and RailtownRateLimitError. Other 4xx responses use RailtownError; 5xx responses use RailtownServerError. Transport failures use RailtownTransportError, timeouts its subclass RailtownTimeoutError, and invalid response JSON/envelopes use RailtownResponseError. For retrieval (rail-engine), import these exceptions from railtown.engine. For ingestion (rail-engine-ingest), import them from railtown.engine.ingest. The railtown.engine.ingest namespace requires rail-engine-ingest; it is not included in the retrieval wheel.
Request/response errors expose status_code when available, operation, the effective engine_id, request_id when available, and retryable. Retryable is true for timeouts, connection failures, and HTTP 408, 429, 502, 503, and 504. It describes a potentially transient failure, not whether replaying a write is safe. The SDK does not retry automatically.
Diagnostic compatibility change: SDK-generated errors now leave response_text as None. The constructor still accepts an explicitly supplied value. Messages exclude query strings and payloads, but the preserved original exception cause can retain sensitive data. Full traceback logging is not guaranteed to be sanitized. Explicit content logging remains governed by LoggingPolicy and does not populate error attributes.
Requirements
- uv
- Python 3.11+
- httpx >= 0.24.0
- pydantic >= 1.10.0
Related package
For ingesting data into Railengine, install and use rail-engine-ingest.
License
MIT
Metadata
Release files for rail-engine 0.5.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| rail_engine-0.5.0.tar.gz | 27.7 kB | Without provenance | Details for rail_engine-0.5.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| rail_engine-0.5.0-py3-none-any.whl | Python 3 | none | any | Details for rail_engine-0.5.0-py3-none-any.whl |
Total release size: 58.1 kB
Release files / rail_engine-0.5.0.tar.gz
| Download URL | rail_engine-0.5.0.tar.gz |
|---|---|
| Size | 27.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
197850c37d77ef952a2ecb1f2d15ef3749995884cb1b32dbd16d8fcc467bf6b6
|
|
BLAKE2b-256 checksum How to use checksums |
5f56f211222b44bcb4b373664c6643cf6000c42b796409ecd2decb623560a3ab
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.5 {"installer":{"name":"uv","version":"0.13.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / rail_engine-0.5.0-py3-none-any.whl
| Download URL | rail_engine-0.5.0-py3-none-any.whl |
|---|---|
| Size | 30.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
75877e8ddaacc5e6b70e8376aaea0f2aee844c99c98b85b55cecd502d4a2b366
|
|
BLAKE2b-256 checksum How to use checksums |
ac7c2dbe5ede17e5be67b37cffc9118d4fb3cd6aef62f051603a5bec034fbbc0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.5 {"installer":{"name":"uv","version":"0.13.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for rail-engine 0.5.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.