Metadata-Version: 2.4
Name: saina
Version: 0.1.0rc1
Summary: Saina HTTP SDK and optional Helm model inference
License-Expression: Apache-2.0
Project-URL: Homepage, https://saina.run
Project-URL: Repository, https://github.com/run-saina/saina
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Provides-Extra: local
Requires-Dist: torch<3,>=2.5; extra == "local"
Requires-Dist: transformers<6,>=5.3; extra == "local"
Requires-Dist: accelerate<2,>=1; extra == "local"
Requires-Dist: peft<0.22,>=0.21; extra == "local"
Requires-Dist: safetensors<1,>=0.4; extra == "local"
Requires-Dist: huggingface-hub<2,>=0.27; extra == "local"
Provides-Extra: server
Requires-Dist: fastapi<1,>=0.115; extra == "server"
Requires-Dist: uvicorn<1,>=0.30; extra == "server"
Requires-Dist: pydantic<3,>=2.9; extra == "server"
Dynamic: license-file

# Saina

Saina's HTTP SDK, shared decision contract, and optional Helm local inference.
Saina is operated by **Rama Labs Inc.** Website: https://saina.run.

**Pre-release source:** packages and model weights are not published yet.
The current private model candidate is not cleared for commercial distribution.
The Apache-2.0 code license does not grant rights to third-party weights or data.

## Install from source

```sh
pip install .                # dependency-free HTTP client
pip install '.[local,server]' # local inference and authenticated server
```

```python
from saina import Saina

client = Saina('https://your-endpoint.example', api_key='YOUR_KEY')

result = client.ask(
    model='helm-0.8b',
    state='I was charged twice.',
    questions={
        'issue': {
            'type': 'single_choice',
            'question': 'Identify the banking issue.',
            'options': {
                'duplicate': 'duplicate charge',
                'delivery': 'card delivery',
            },
        },
    },
)
```

Keep credentials in environment variables or a secret manager, not source files.

## Transformers / local inference

```python
from saina import register_transformers
from transformers import pipeline

register_transformers()

helm = pipeline(
    'saina-classification',
    model='/path/to/staged/checkpoint',
    device='cuda:0',
    model_kwargs={'device': 'cuda:0'},
)

probabilities = helm({
    'task': 'Identify the banking issue.',
    'input': 'I was charged twice.',
    'choices': ['duplicate charge', 'card delivery'],
    'mode': 'single_label',
})
```

Use `multi_label` for independent memberships; output order always follows choices.
Lists of requests are supported serially, not optimized tensor batching. Hub loading
requires an immutable revision and installed registration code, not remote code.
CPU operation is supported by the loader but is not an optimized ONNX release.

## JavaScript / TypeScript

Source: `clients/javascript`; planned registry package: `@run-saina/sdk`.
Exports `Saina` and `SainaError`, retaining `SainaHelm` aliases for compatibility.

## Serving and contracts

Set `SAINA_API_KEY`, `SAINA_CHECKPOINT`, `SAINA_DEVICE` and optionally
`SAINA_REVISION` (pinned Hub commit), then:

```sh
uvicorn saina.server:create_app --factory --host 127.0.0.1 --port 8000
```

Native typed requests use `/v1/ask`. The `saina.contract` module owns their schema.
`saina.jev` provides the Jev/System One adapter; endpoint wiring is separate.
Do not expose a plain HTTP server publicly; place it behind authenticated TLS.

## Development

`PYTHONPATH=src python -m unittest discover -s tests`
and `cd clients/javascript && npm test`.

No training datasets, private history, model weights, or credentials are included.
