Metadata-Version: 2.4
Name: ara-sdk
Version: 0.1.56
Summary: Public Python SDK for building and running Ara apps.
Project-URL: Homepage, https://github.com/Aradotso/ara-python-sdk
Project-URL: Documentation, https://docs.ara.so/sdk/overview
Project-URL: Issues, https://github.com/Aradotso/ara-python-sdk/issues
Author-email: Ara <support@ara.so>
License: Proprietary
License-File: LICENSE
Keywords: agents,ai,ara,sdk
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: certifi
Description-Content-Type: text/markdown

# Ara Python SDK

Ara is a managed platform for building and running long-lived AI agents in the cloud.

The `ara-sdk` is the Python layer for defining those agents and tools in code using a minimal authoring model. Ara runs the cloud runtime and operations, while the SDK focuses on compact automation scripts.

## Overview

To program on Ara, you compose workflows with two primitives: `ara.Automation(...)` (system behavior) and `@ara.tool` (custom callable behavior attached to that automation).

Runtime flow:

```text
              +------------------------------+
              | Messages (iMessage/SMS/RCS)  |
              +------------------------------+
                        ^
                        |
                        v
              +----------------------------------------------+
              |         Ara Cloud: 24/7 Agent Runtime        |
              |  - Routes automation runs and tool calls     |
              |  - Maintains runtime context and state       |
              |                                              |
              |  +------------------------+                  |
              |  |   Sandbox / Computer   |                  |
              |  | - File system access   |                  |
              |  | - Executes tasks/tools |                  |
              |  +------------------------+                  |
              +-------------------+--------------------------+
                                  ^
                                  |
        +-------------------------+-------------------------+
        |                         |                         |
+------------------------+ +--------------------------+ +-----------------------------+
|   Built-in tools       | |    Connector tools       | |   SDK custom tools          |
| - File browse/edit     | | - Enabled in app.ara.so  | | - Python functions via      |
| - Program execution    | | - External integrations  | |   @ara.tool                 |
+------------------------+ +--------------------------+ +-----------------------------+
```

Quickstart:

```bash
pip install ara-sdk
```

```python
import ara_sdk as ara

@ara.tool
def utc_now() -> dict:
    from datetime import datetime, timezone
    return {"utc_time": datetime.now(timezone.utc).isoformat()}

ara.Automation(
    "hello-hourly-agent",
    system_instructions=(
        "Reply with one short hello message and include UTC time. "
        "If linq_send_message is available and a phone route is paired, "
        "send the same message there once."
    ),
    tools=[utc_now],
)
```

Connector tools are enabled by default. To disable connector access for an automation, pass `allow_connector_tools=False`.

Non-interactive auth (no `ara auth login`) is supported via `ARA_API_KEY`:

```bash
ARA_API_KEY="<your_key>" ara deploy app.py
ara run app.py
```

Runtime CLI commands also use the same auth source (`ara auth login` credentials or `ARA_API_KEY`) and do not require separate runtime/API-session tokens:

```bash
ara runtime session start
ara runtime tools available --session <session_id>
ara runtime session exec --command "ls -la /root/.ara/workspace"
ara runtime files read --path notes/todo.txt
ara runtime files write --path notes/todo.txt --content "updated from cli"
ara runtime files upload --local ./draft.md --path notes/draft.md
ara runtime files download --path notes/draft.md --output ./draft-copy.md
```

`ara runtime files *` targets your active personal session directly, so it does not take a `--session` flag.


## Run maintained examples

Examples: [github.com/Aradotso/ara-python-sdk/tree/main/examples](https://github.com/Aradotso/ara-python-sdk/tree/main/examples)

## FAQ

### What is the difference between Ara and `ara-sdk`?
Ara is the managed control/runtime plane (execution, lifecycle, policy, observability), while `ara-sdk` is the authoring layer for automation behavior (tools + instructions). You define Python app logic; Ara handles runtime operations you would otherwise run as custom infrastructure.

### Does “24/7 runtime” mean I pay for permanently hot compute?
Not inherently. The runtime is always available as the service boundary, but sandbox/task compute can activate on demand from schedules, events, and API calls. Practical cost and footprint depend on your trigger frequency and runtime policy. _Note: today usage is billed under your existing Pro or Ultra subscription._

### How should I think about `Automation`, `@tool`, and `secret(...)`?
Use `Automation(...)` as the top-level app declaration, `@tool` for deterministic capability execution, and `secret("KEY")` when a tool requires credentials. Schedules are configured in app.ara.so UI to avoid code/UI drift.

### How do connectors work in `Automation(...)`?
Connector tools are enabled by default (`allow_connector_tools=True`). Set `allow_connector_tools=False` for strict mode, then explicitly scope allowed connector actions with `skills=[ara.connectors.<toolkit>[.<action>]]`.

### Do tools have to return a `dict`?
No. Tool functions can return any JSON-serializable value (`dict`, `list`, `str`, `int`, `float`, `bool`, or `None`). The runtime serializes structured values to JSON and provides tool output back to the model as text.

### How do I handle secrets and environment safely at scale?
Declare required credentials in code with `secret("KEY")` and provide values through Ara secret sync at deploy time (or pre-provisioned app secrets). Keep all secret values out of source control.

### Do I need public endpoints to use Ara?
No. The minimal SDK is automation-first; public endpoint wiring is not part of this authoring surface.
