Metadata-Version: 2.4
Name: earthinia
Version: 1.0.0
Summary: Official Python SDK for the Earthinia AI Workforce Platform.
Author-email: Earthinia <support@eacse.com>
Maintainer-email: Earthinia <support@eacse.com>
License-Expression: MIT
Project-URL: Homepage, https://earthinia.com
Project-URL: Documentation, https://docs.earthinia.com
Project-URL: Source, https://github.com/kilan-go/earthinia-platform/tree/main/packages/sdk-python
Project-URL: Issues, https://github.com/kilan-go/earthinia-platform/issues
Keywords: earthinia,ai,agents,assistant,automation,llm,workforce,enterprise,sdk
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Classifier: Topic :: Internet
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.32.0
Requires-Dist: pydantic<3,>=2.11.0
Provides-Extra: dev
Requires-Dist: pytest>=8.4.0; extra == "dev"
Requires-Dist: pytest-cov>=6.2.0; extra == "dev"
Requires-Dist: pytest-asyncio>=1.1.0; extra == "dev"
Requires-Dist: ruff>=0.12.0; extra == "dev"
Requires-Dist: mypy>=1.17.0; extra == "dev"
Requires-Dist: build>=1.3.0; extra == "dev"
Requires-Dist: twine>=6.1.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.6.0; extra == "docs"
Requires-Dist: mkdocs-material>=9.6.0; extra == "docs"
Dynamic: license-file

# Earthinia Python SDK

The official synchronous Python client for the Earthinia public REST API. Requires Python 3.10+.
This directory is the source of the `earthinia` distribution; registry installation requires a published release.

## Install

After release:

```bash
pip install earthinia
```

## Execute a prompt

Create a public API key for an existing cluster in the Earthinia Console. The key must have
`cluster:<cluster_id>:chat` scope. Replace the cluster ID below with that cluster's ID.

```python
from earthinia import Earthinia

with Earthinia(api_key="earth_live_...") as client:
    response = client.chat.create(
        cluster_id="your-cluster-id",
        message="Prepare today's sales report.",
    )
    print(response.text)
```

The key above is a placeholder, not a usable credential. Keep real keys on your server.
You can also use environment-variable authentication:

```bash
export EARTHINIA_API_KEY="earth_live_..."
```

```python
from earthinia import Earthinia

with Earthinia() as client:
    response = client.clusters.execute(
        "your-cluster-id", "Prepare today's sales report.", session_id="sales-report"
    )
    print(response.text)
```

An explicit `api_key` takes precedence over `EARTHINIA_API_KEY`. The client does not load `.env` files.
Reuse a client for connection pooling; use it as a context manager or call `client.close()`.

## Contract and behavior

Both `chat.create` and `clusters.execute` call
`POST https://api.eacse.com/api/v1/clusters/{cluster_id}/chat` using `X-Earthinia-Key`.
The server derives account identity and permissions from the key. User identity cannot be overridden.
`chat.create` also accepts `session_id`, `metadata`, `attachments`, and `output_format`.
Attachment objects follow the public API contract; the client does not read or upload local files implicitly.
Responses are generated Pydantic models with `text`, `success`, `status`, `session_id`, `usage`, and other API fields.
The `earthinia.models.ChatResponse` alias refers to the generated response model.

The production origin defaults to `https://api.eacse.com`. Set `base_url` to an HTTPS origin
without `/api`; the client adds the full API path. Loopback HTTP is allowed for local development:

```python
client = Earthinia(base_url="http://localhost:8001", timeout=60)
```

`timeout` is a positive number of seconds (default 30), applied to connection and read operations.
It is not an end-to-end execution deadline. TLS verification stays enabled. Redirects are not followed.
Environment proxy and netrc settings are not used. Prompt submissions are never retried automatically:
a timeout may occur after execution has begun, so check the operation before submitting it again.

```python
from earthinia.exceptions import AuthenticationError, EarthiniaError, RateLimitError

try:
    with Earthinia() as client:
        response = client.chat.create("your-cluster-id", "Prepare today's sales report.")
except AuthenticationError:
    print("Configure a valid API key.")
except RateLimitError as error:
    print("Rate limited; retry-after seconds:", error.retry_after)
except EarthiniaError as error:
    print(error.status_code, str(error))
```

HTTP failures raise SDK exceptions; malformed successful responses raise `SerializationError`.
Exception messages omit remote bodies and headers to avoid exposing credentials or user data.
The SDK does not log requests or keys.

## Supported surface

This release supports public-key chat and cluster prompt execution. Cluster administration,
files, sessions, streaming, and other account-management APIs are not exposed by this client.
Earlier README examples advertised unimplemented operations and a nonexistent async client;
there is no `AsyncEarthinia` or `run()` method. Use the actual methods above.
The former administrative cluster methods targeted nonexistent public-key endpoints and have
been removed from the client surface. `user_id` overrides are rejected. Chat responses are now
Pydantic objects; use `.model_dump()` or `.model_dump_json()` when you need serialized data.

The optional CLI uses the same key and endpoint:

```bash
earthinia your-cluster-id "Prepare today's sales report."
```

## Development and release

From this SDK directory:

```bash
python -m pip install '.[dev]'
python -m pytest
python -m build
python -m twine check dist/*
python ../../scripts/check-sdk-artifacts.py dist/*
python ../../scripts/test-python-sdk-install.py dist/*.whl
```

See [the monorepo release guide](https://github.com/kilan-go/earthinia-platform/blob/main/docs/sdk-releases.md)
for contract regeneration, independent versioning, and PyPI Trusted Publishing setup.

## License

MIT. See LICENSE.
