Metadata-Version: 2.5
Name: kalcend
Version: 0.9.1
Summary: Kalcend Python SDK — execute Kalcend tools from any agent runtime; ships a Hermes plugin for hosted Teammates.
License-Expression: MIT
License-File: LICENSE
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.9
Provides-Extra: df
Requires-Dist: pandas; extra == 'df'
Description-Content-Type: text/markdown

# kalcend

Execute Kalcend tools from Python. Designed for use inside OpenAI shell containers.

## Install

```bash
pip install kalcend
```

## 0.9.1

- Durable hosted-teammate inbox receipts, queued-turn authorization, and
  recovery notices when interrupted work cannot safely be replayed.
- Media job status lookup and original chat, thread, and sender propagation.
- Coordinated token refresh and environment persistence across reinstall.
- MCP credential/environment validation and installed-readiness checks.

Hosted features require the matching Kalcend runtime and platform configuration.

## Usage

```python
from kalcend import run, run_df, download, upload

# Execute any tool
result = run("db_query", query="SELECT * FROM users", credential_id="cred_123")

# Get results as a DataFrame
df = run_df("db_query", query="SELECT * FROM orders", credential_id="cred_123")

# Download a file from the org store
download("file_abc", "/mnt/data/input.csv")

# Upload a file to the org store
upload("/mnt/data/chart.png", "Q1_Chart.png")
```

For media generated through the AWS runtime, inspect the returned job ID
without submitting another generation:

```python
from kalcend import media_status, download

state = media_status("med_existing_job_id")
if state["status"] == "done" and state["file_available"]:
    download(state["file_id"], "/mnt/data/generated-asset")
elif state["status"] == "failed":
    print(state["message"])
```

`queued` or `running` means check the same job later. A failed job's message
does not include private provider diagnostics.

## Environment

- `KALCEND_TOKEN` — JWT token (auto-injected by OpenAI domain_secrets)
- `KALCEND_BASE_URL` — API base URL (default: `https://kalcend.ai/api/providers/agentexec`)
