earthinia 1.0.0__tar.gz

earthinia-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Earthinia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

earthinia-1.0.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include README.md LICENSE pyproject.toml
+recursive-include earthinia *.py py.typed
+prune tests
+global-exclude .env .env.* *.pem *.key *.pyc

earthinia-1.0.0/PKG-INFO

@@ -0,0 +1,167 @@
+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.

earthinia-1.0.0/README.md

@@ -0,0 +1,124 @@
+# 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.

earthinia-1.0.0/earthinia/__init__.py

@@ -0,0 +1,6 @@
+"""Public entry point for the Earthinia REST SDK."""
+
+from .client import Earthinia
+from ._version import __version__
+
+__all__ = ["Earthinia", "__version__"]

earthinia-1.0.0/earthinia/_version.py

@@ -0,0 +1,3 @@
+from importlib.metadata import version
+
+__version__ = version("earthinia")

earthinia-1.0.0/earthinia/auth.py

@@ -0,0 +1,14 @@
+from ._version import __version__
+
+
+class APIKeyAuth:
+    def __init__(self, api_key: str):
+        self._api_key = api_key
+
+    @property
+    def headers(self) -> dict[str, str]:
+        return {
+            "X-Earthinia-Key": self._api_key,
+            "Accept": "application/json",
+            "User-Agent": f"earthinia-python/{__version__}",
+        }

earthinia-1.0.0/earthinia/client.py

@@ -0,0 +1,29 @@
+"""Synchronous public API client; no server dependencies are imported."""
+import os
+
+from .auth import APIKeyAuth
+from .config import SDKConfig
+from .exceptions import AuthenticationError
+from .resources.chat import ChatResource
+from .resources.clusters import ClusterResource
+from .transport import Transport
+
+
+class Earthinia:
+    def __init__(self, api_key: str | None = None,
+                 base_url: str = "https://api.eacse.com", *, timeout: float = 30.0):
+        key = api_key if api_key is not None else os.getenv("EARTHINIA_API_KEY")
+        if not isinstance(key, str) or not key.strip() or any(c.isspace() for c in key):
+            raise AuthenticationError("Provide api_key or set EARTHINIA_API_KEY to a non-empty API key.")
+        self._transport = Transport(SDKConfig(key, base_url, timeout), APIKeyAuth(key))
+        self.chat = ChatResource(self._transport)
+        self.clusters = ClusterResource(self._transport)
+
+    def close(self) -> None:
+        self._transport.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *_):
+        self.close()

earthinia-1.0.0/earthinia/config.py

@@ -0,0 +1,23 @@
+"""Validated connection settings. API keys are excluded from representations."""
+from dataclasses import dataclass, field
+import math
+from urllib.parse import urlsplit
+
+from .exceptions import ConfigurationError
+
+
+@dataclass
+class SDKConfig:
+    api_key: str = field(repr=False)
+    base_url: str = "https://api.eacse.com"
+    timeout: float = 30.0
+
+    def __post_init__(self):
+        self.base_url = self.base_url.rstrip("/")
+        url = urlsplit(self.base_url)
+        local = url.hostname in {"localhost", "127.0.0.1", "::1"}
+        if (not url.hostname or url.username or url.password or url.query or url.fragment
+                or url.path or not (url.scheme == "https" or (url.scheme == "http" and local))):
+            raise ConfigurationError("base_url must be an HTTPS origin (HTTP is allowed on loopback for development).")
+        if not math.isfinite(self.timeout) or self.timeout <= 0:
+            raise ConfigurationError("timeout must be a positive finite number of seconds.")

earthinia-1.0.0/earthinia/console.py

@@ -0,0 +1,47 @@
+"""Command-line entry point for cluster prompts."""
+
+import argparse
+import base64
+import mimetypes
+import os
+from pathlib import Path
+
+from .client import Earthinia
+
+
+def main():
+    parser = argparse.ArgumentParser(prog="earthinia")
+    parser.add_argument("cluster_id")
+    parser.add_argument("prompt")
+    parser.add_argument("--session", default="console")
+    parser.add_argument("--file", action="append", default=[])
+    parser.add_argument("--format", default="text")
+    parser.add_argument("--base-url", default=os.getenv("EARTHINIA_BASE_URL", "https://api.eacse.com"))
+    args = parser.parse_args()
+
+    attachments = []
+    for filename in args.file:
+        path = Path(filename)
+        attachments.append({
+            "filename": path.name,
+            "mime_type": mimetypes.guess_type(path.name)[0] or "application/octet-stream",
+            "content_base64": base64.b64encode(path.read_bytes()).decode(),
+        })
+
+    client = Earthinia(
+        api_key=os.getenv("EARTHINIA_API_KEY"),
+        base_url=args.base_url,
+    )
+    result = client.clusters.execute(
+        args.cluster_id,
+        args.prompt,
+        args.session,
+        attachments=attachments,
+        output_format=args.format,
+    )
+    print(result.model_dump_json(indent=2))
+    client.close()
+
+
+if __name__ == "__main__":
+    main()

earthinia-1.0.0/earthinia/exceptions.py

@@ -0,0 +1,170 @@
+"""
+Earthinia SDK Exceptions
+
+Provides the complete exception hierarchy used by the SDK.
+
+Applications should catch the most specific exception possible.
+
+Example:
+
+    try:
+        client.chat.create(request)
+    except AuthenticationError:
+        ...
+    except RateLimitError:
+        ...
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class EarthiniaError(Exception):
+    """
+    Base class for all Earthinia SDK exceptions.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        request_id: str | None = None,
+        error_code: str | None = None,
+        details: Any = None,
+    ) -> None:
+
+        super().__init__(message)
+
+        self.message = message
+        self.status_code = status_code
+        self.request_id = request_id
+        self.error_code = error_code
+        self.details = details
+
+    def __str__(self) -> str:
+
+        parts = [self.message]
+
+        if self.status_code is not None:
+            parts.append(f"(status={self.status_code})")
+
+        if self.error_code:
+            parts.append(f"[{self.error_code}]")
+
+        if self.request_id:
+            parts.append(f"request_id={self.request_id}")
+
+        return " ".join(parts)
+
+
+# ---------------------------------------------------------------------
+# Client Errors
+# ---------------------------------------------------------------------
+
+
+class AuthenticationError(EarthiniaError):
+    """
+    Invalid or expired API key.
+    """
+
+
+class AuthorizationError(EarthiniaError):
+    """
+    User is authenticated but lacks permissions.
+    """
+
+
+class ValidationError(EarthiniaError):
+    """
+    Invalid request payload.
+    """
+
+
+class ResourceNotFoundError(EarthiniaError):
+    """
+    Requested resource does not exist.
+    """
+
+
+class ConflictError(EarthiniaError):
+    """
+    Resource conflict.
+    """
+
+
+class RateLimitError(EarthiniaError):
+    """
+    API rate limit exceeded.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        retry_after: int | None = None,
+        **kwargs: Any,
+    ) -> None:
+
+        super().__init__(message, **kwargs)
+
+        self.retry_after = retry_after
+
+
+# ---------------------------------------------------------------------
+# Server Errors
+# ---------------------------------------------------------------------
+
+
+class ServerError(EarthiniaError):
+    """
+    Internal Earthinia server error.
+    """
+
+
+class ServiceUnavailableError(ServerError):
+    """
+    Earthinia service temporarily unavailable.
+    """
+
+
+class TimeoutError(ServerError):
+    """
+    Request timed out.
+    """
+
+
+# ---------------------------------------------------------------------
+# SDK Errors
+# ---------------------------------------------------------------------
+
+
+class ConfigurationError(EarthiniaError):
+    """
+    Invalid SDK configuration.
+    """
+
+
+class ConnectionError(EarthiniaError):
+    """
+    Network connection failed.
+    """
+
+
+class SerializationError(EarthiniaError):
+    """
+    Failed to serialize or deserialize data.
+    """
+
+
+class StreamingError(EarthiniaError):
+    """
+    Streaming connection failed.
+    """
+
+
+class WebSocketError(EarthiniaError):
+    """
+    WebSocket connection failed.
+    """

earthinia-1.0.0/earthinia/generated.py

@@ -0,0 +1,66 @@
+# generated by datamodel-codegen:
+#   filename:  public.openapi.json
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class Status(Enum):
+    completed = 'completed'
+    failed = 'failed'
+    needs_input = 'needs_input'
+
+
+class ExecutionError(BaseModel):
+    code: str = Field(..., title='Code')
+    details: dict[str, Any] | None = Field(None, title='Details')
+    message: str = Field(..., title='Message')
+    retryable: bool | None = Field(False, title='Retryable')
+
+
+class PublicChatRequest(BaseModel):
+    attachments: list[dict[str, Any]] | None = Field(None, title='Attachments')
+    channel: str | None = Field('api', title='Channel')
+    message: str = Field(..., title='Message')
+    metadata: dict[str, Any] | None = Field(None, title='Metadata')
+    output_format: str | None = Field('text', title='Output Format')
+    session_id: str | None = Field(None, title='Session Id')
+
+
+class ValidationError(BaseModel):
+    ctx: dict[str, Any] | None = Field(None, title='Context')
+    input: Any | None = Field(None, title='Input')
+    loc: list[str | int] = Field(..., title='Location')
+    msg: str = Field(..., title='Message')
+    type: str = Field(..., title='Error Type')
+
+
+class ChatResponse(BaseModel):
+    model_config = ConfigDict(
+        extra='forbid',
+    )
+    account_id: str = Field(..., title='Account Id')
+    channel: str = Field(..., title='Channel')
+    cluster_id: str = Field(..., title='Cluster Id')
+    detail: str | None = Field(None, title='Detail')
+    error: ExecutionError | None = None
+    id: str = Field(..., title='Id')
+    message: dict[str, Any] = Field(..., title='Message')
+    operations: dict[str, Any] | None = Field(None, title='Operations')
+    output: dict[str, Any] | None = Field(None, title='Output')
+    provider_event_id: str | None = Field(..., title='Provider Event Id')
+    request_id: str = Field(..., title='Request Id')
+    result: dict[str, Any] = Field(..., title='Result')
+    session_id: str = Field(..., title='Session Id')
+    status: Status = Field(..., title='Status')
+    success: bool = Field(..., title='Success')
+    text: str | None = Field('', title='Text')
+    usage: dict[str, int] | None = Field(None, title='Usage')
+
+
+class HTTPValidationError(BaseModel):
+    detail: list[ValidationError] | None = Field(None, title='Detail')