Metadata-Version: 2.4
Name: rail-engine-ingest
Version: 0.2.0
Summary: Python SDK for Railtown AI Rail Engine - Ingestion
Author-email: Railtown AI <support@railtown.ai>
License: MIT
Project-URL: Homepage, https://github.com/railtownai/railengine-sdk
Project-URL: Documentation, https://github.com/railtownai/railengine-sdk
Project-URL: Repository, https://github.com/railtownai/railengine-sdk
Keywords: railtown,rail-engine,ingestion,sdk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.24.0
Requires-Dist: pydantic>=1.10.0
Dynamic: license-file

# Rail Engine Ingestion SDK

Python SDK for ingesting data into Railtown AI Rail Engine - handles embeddings, storage, indexing, and webhook publishing.

## Overview

The `rail-engine-ingest` package provides a Pythonic interface for publishing data to Rail Engine. It supports async/await patterns, Pydantic model validation, and familiar configuration patterns.

## Installation

```bash
uv pip install rail-engine-ingest
```

## Quick Start

```python

# Copy your ENGINE_TOKEN from https://cndr.railtown.ai Project Settings

import asyncio
import os
from railtown.engine.ingest import RailengineIngest
import base64
import json

engine_token = os.getenv("ENGINE_TOKEN")

async def main():
    # Initialize client
    async with RailengineIngest(engine_token=engine_token) as client:
        # Ingest data
        data = {
            "name": "Chicken Shawarma",
            "meal": "lunch",
            "calories": 95
        }
        response = await client.upsert(data)
        print(f"Status: {response.status_code}")

asyncio.run(main())
```

## Configuration

### Environment Variable

- `ENGINE_TOKEN` - Base64-encoded JSON string containing ingestion credentials

### Constructor Parameters

- `engine_token` (optional) - ENGINE_TOKEN string (if not provided, reads from env)
- `model` (optional) - Pydantic model type for validating ingested data

## Features

- **Single `upsert()` method** - Unified interface for ingesting data
- **Multiple data formats** - Accepts Pydantic models, dictionaries, or JSON strings
- **Model validation** - Optional Pydantic model validation
- **Direct JSON payload** - Sends data directly as JSON to the ingestion endpoint
- **Webhook handler** - `get_webhook_handler()` returns a payload parser when the client is constructed with `model=`
- **Async/await support** - Built for modern async Python applications

## Error Handling

The SDK provides custom exception classes:

- `RailtownError` - Base exception
- `RailtownBadRequestError` - 400 Bad Request
- `RailtownUnauthorizedError` - 401 Unauthorized
- `RailtownNotFoundError` - 404 Not Found
- `RailtownConflictError` - 409 Conflict
- `RailtownServerError` - 5xx Server errors

Exceptions are raised on errors.

## Requirements

- uv
- Python 3.10+
- httpx >= 0.24.0
- pydantic >= 1.10.0

## Related package

For retrieving and searching data from Rail Engine, install and use [`rail-engine`](https://pypi.org/project/rail-engine/).

## License

MIT
