Metadata-Version: 2.4
Name: tron-client-py
Version: 0.1.3
Summary: AI compute orchestrator for self-hosted Python workloads, with transparent remote execution and MagicFuture semantics.
Author: TRON
Keywords: tron,distributed-computing,ai-orchestration,ray-alternative,self-hosted-compute,python,workflow,local-first
Classifier: Programming Language :: Python :: 3.12
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: System :: Distributed Computing
Classifier: Operating System :: OS Independent
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi==0.125.0
Requires-Dist: uvicorn==0.49.0
Requires-Dist: requests==2.32.0
Requires-Dist: cloudpickle==3.0.0
Requires-Dist: pydantic==1.10.26
Requires-Dist: streamlit==1.58.0
Requires-Dist: pandas==3.0.3
Requires-Dist: numpy==2.1.3
Requires-Dist: streamlit-autorefresh==1.0.1
Dynamic: license-file

# TRON

**TRON is an AI Compute Orchestrator for self-hosted Python workloads.**

Designed to bypass heavy enterprise DevOps and deliver distributed compute without cluster complexity.

- **AI-first SDK:** `@tron.remote` makes normal Python functions run across workers with transparent futures.
- **Self-hosted control:** deploy on your own hardware, cloud, Docker, or laptop — no managed vendor lock-in.
- **PyPI-ready package:** `tron-client-py` is built as a lightweight orchestration SDK for AI engineering teams.

Make distributed compute feel like local Python:

```python
import tron

# Ensure a TRON server is available automatically.
# This will connect to an existing server or start a local one.
tron.ensure_server()

@tron.remote
def expensive_task(x):
    return x * 2

result = expensive_task(10).get()
```

With the current SDK, developers can treat TRON as a client-first platform: the SDK auto-discovers or starts a local runtime as needed, so they rarely need to run `queue_server.py` manually.

For local development, the SDK also supports launching a complete local runtime automatically:

```python
tron.start_local_environment()
# ... run remote tasks ...
tron.stop_local_worker()
```

You can also start a worker directly if you want to control just the worker lifecycle:

```python
tron.start_local_worker()
# ... run remote tasks ...
tron.stop_local_worker()
```

## Why TRON?

- **AI compute orchestration made simple:** One SDK, one decorator, no cluster YAML.
- **Works everywhere:** Cloud, on-prem, laptop, VPS, Kubernetes.
- **Own your data:** Your server, your rules, no vendor lock-in.
- **Scales smoothly:** From local IDE testing to self-hosted production.
- **Feels like native Python:** `@tron.remote`, `.get()`, and you're done.

## TRON vs. Ray vs. Celery

| Capability | TRON | Ray | Celery |
|---|---|---|---|
| Client-first Python SDK | ✅ `@tron.remote` with local-first auto-discovery | ⚠️ ray.remote requires Ray cluster/runtime | ⚠️ separate task and broker setup |
| Transparent future semantics | ✅ `MagicFuture` with `.get()` and status polling | ✅ `ObjectRef` / `ray.get()` | ✅ `AsyncResult` / `get()` |
| Zero enterprise cluster YAML | ✅ self-hosted backend, Docker, cloud, laptop | ⚠️ cluster config can be heavy | ⚠️ broker + worker topology required |
| Self-hosted / data residency friendly | ✅ built for private infrastructure | ⚠️ best with Ray cluster / managed Ray | ⚠️ broker hosted or internal broker setup |
| Fast onboarding for dev teams | ✅ install SDK, annotate functions, run | ⚠️ install Ray/cluster + runtime | ⚠️ install broker + worker services |
| Best for AI engineering / model pipelines | ✅ orchestrates compute across workers with local-first ergonomics | ✅ supports distributed ML workloads | ⚠️ more task queue than compute orchestration |

TRON is purpose-built for teams that want distributed power without complex cluster configuration errors. Its `@tron.remote` decorator and `MagicFuture` engine make the developer experience predictable and transparent.

## Enterprise & Sovereign Compliance Support

**Enterprise & Sovereign Compliance Support**

*Running TRON in a highly regulated banking, fintech, or sensitive AI cluster? If you require dedicated self-hosted deployment architecture, compliance auditing under NDPR data residency laws, or a custom service-level agreement (SLA), please connect directly with our engineering desk.*

For enterprise intake, use the project contact portal: https://tally.so/r/your-enterprise-intake or your preferred calendar booking page.

## Install the SDK

```bash
# Local install while the package is not yet published to PyPI
python -m pip install dist/tron_client-0.1.3-py3-none-any.whl
```

If you want the published release wheel, install directly from GitHub:

```bash
pip install https://github.com/StarkX-cloud/tron-client/releases/download/v0.1.3/tron_client-0.1.3-py3-none-any.whl
```

Once `tron-client-py` is published to PyPI, this can become:

```bash
python -m pip install tron-client-py
```

If you are developing the repo itself, use:

```bash
python -m venv .venv
.\\.venv\\Scripts\\Activate.ps1
pip install -r requirements.txt
```

## Basic usage

```python
import tron

@tron.remote
def add_numbers(a, b):
    return a + b

result = add_numbers(1, 2).get()
print(result)
```

## Client-side flow

Users should only ever do this:

1. install the SDK locally for now: `python -m pip install dist/tron_client-0.1.3-py3-none-any.whl`
   - once published, this becomes: `python -m pip install tron-client-py`
2. write Python functions with `@tron.remote`
3. optionally configure the backend URL with `tron.config(...)`
4. call `.get()` on futures

Example:

```python
import tron

tron.config("http://localhost:9000")

@tron.remote
def add(a, b):
    return a + b

print(add(2, 3).get())
```

## Quick Start: Deploy your own TRON

Pick your platform and deploy in minutes:

### Cloud Run (free tier, easiest)
```bash
./deploy/cloud-run-quick.sh
```

### Fly.io (global, free tier)
```bash
./deploy/fly-quick.sh
```

### Render (simple web service)
```bash
./deploy/render-quick.sh
```

### Local Docker (dev/testing)
```bash
docker compose up
```

See [SELF_HOST.md](SELF_HOST.md) for detailed guides and customization.

This repo includes a `Dockerfile` and `docker-compose.yml` for an always-on backend.

```bash
docker compose up --build
```

If you want background mode:

```bash
docker compose up --build -d
```

The local API will be available at:

- `http://localhost:9000`

If Docker is unstable, use the direct Python run above instead.

## Developer workflow

Once your team deploys a TRON server, developers:

1. Install the SDK locally for now: `python -m pip install dist/tron_client-0.1.3-py3-none-any.whl`
   - once published, this becomes: `python -m pip install tron-client`
2. Get the server URL from your team
3. Add to code:
   ```python
   import tron
   tron.config("https://your-team-server")
   ```
4. Write normal Python with `@tron.remote`
5. Call `.get()` to fetch results

Developers do not need to run or change `queue_server.py`.
That file is the backend server implementation, and it is managed by your infrastructure or operations team.

See [USER_GUIDE.md](USER_GUIDE.md) for detailed examples.

## How TRON is structured

- `tron/` — client SDK, `@remote` decorator, `MagicFuture` for transparent `.get()`
- `queue_server.py` — FastAPI backend, job submission, status tracking
- `worker.py` — task execution, resource management
- `Dockerfile` — containerized runtime for any cloud
- `.github/workflows/deploy-cloud-run.yml` — auto-deploy to Cloud Run on push

## Architecture

```
Developer
    |
    | python -m pip install dist/tron_client-0.1.3-py3-none-any.whl
    |
    v
[ @tron.remote decorator ]
    |
    | tron.config("https://server")
    |
    v
[ TRON Backend (self-hosted) ]
    |
    +---> Queue (job storage)
    +---> Workers (parallel execution)
    +---> Results (stream back to SDK)
```

## For operators / infrastructure teams

Your job: deploy TRON once, keep it running.

Developers' job: use the SDK.

Deployment is simple:

1. Pick a platform (Cloud Run, Fly.io, Docker, etc.)
2. Run the deploy script or follow [SELF_HOST.md](SELF_HOST.md)
3. Share the server URL with developers
4. Done

No vendor lock-in. You own the infrastructure.

### Quick deploy

- **Cloud Run:** `bash deploy/cloud-run-quick.sh`
- **Fly.io:** `bash deploy/fly-quick.sh`
- **Local/VPS:** `docker compose up`

See [SELF_HOST.md](SELF_HOST.md) for detailed guides, scaling, and troubleshooting.

## Building the package

If you want to build the client package for distribution:

```bash
python -m pip install --upgrade build
python -m build --sdist --wheel
```

Test locally:

```bash
python -m pip install dist/tron_client-0.1.3-py3-none-any.whl
python -c "import tron; print(tron.__name__)"
```

## Documentation

- [SELF_HOST.md](SELF_HOST.md) - Complete self-hosting guide (Cloud Run, Fly.io, Render, Docker, etc.)
- [USER_GUIDE.md](USER_GUIDE.md) - For developers using TRON
- [QUICKSTART.md](QUICKSTART.md) - Quick usage tutorial
- [deploy/README.md](deploy/README.md) - Deployment reference
- [MAGIC_GUIDE.md](MAGIC_GUIDE.md) - Advanced TRON behavior and design
