Metadata-Version: 2.4
Name: starnus
Version: 1.0.0
Summary: Official Python SDK and CLI for the Starnus AI platform
Author-email: Starnus Team <support@starnustech.com>
License: MIT
Project-URL: Homepage, https://starnus.com
Project-URL: Documentation, https://docs.starnus.com
Keywords: starnus,ai,sdk,automation,agents,cli
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31.0
Requires-Dist: websocket-client>=1.7.0
Requires-Dist: click>=8.1.0
Provides-Extra: pandas
Requires-Dist: pandas>=2.0.0; extra == "pandas"
Requires-Dist: openpyxl>=3.1.0; extra == "pandas"
Provides-Extra: all
Requires-Dist: pandas>=2.0.0; extra == "all"
Requires-Dist: openpyxl>=3.1.0; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: responses>=0.25.0; extra == "dev"
Requires-Dist: ruff>=0.3.0; extra == "dev"
Requires-Dist: mypy>=1.8.0; extra == "dev"
Requires-Dist: types-requests>=2.31.0; extra == "dev"
Dynamic: license-file

# Starnus Python SDK

[![PyPI version](https://img.shields.io/pypi/v/starnus.svg)](https://pypi.org/project/starnus/)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

The official Python SDK for the [Starnus AI platform](https://starnus.com).

Run AI-powered agentic tasks, stream live results over WebSocket, manage projects, upload files, export artifacts, and more — all from Python or the command line.

---

## Installation

```bash
pip install starnus
```

## Quickstart

```python
import starnus

client = starnus.Starnus(api_key="sk_live_your_api_key")

# Create a project
project = client.projects.create(name="Lead Research")

# Run an AI task and stream results live
execution = client.execute(
    project_id=project.id,
    prompt="Find 10 CEOs of software companies in the Netherlands.",
)

for event in execution.stream():
    if event.type == "supervisor_update":
        print(f"[supervisor] {event.message}")
    elif event.type == "result":
        print(f"\nDone: {event.message}")
        break
```

## Authentication

Set your API key as an environment variable:

```bash
export STARNUS_API_KEY="sk_live_your_api_key"
```

Or pass it directly to the client:

```python
client = starnus.Starnus(api_key="sk_live_your_api_key")
```

Get your API key from the [Starnus dashboard](https://app.starnus.com) under **Dev Tools → API Keys**.

## Documentation

Full SDK reference: [starnus.com/docs](https://starnus.com/docs)

Includes:
- All resource methods with parameters and return types
- WebSocket streaming event reference
- File upload, artifact export, and trigger examples
- CLI reference
- Error handling guide

## Resources

| Resource | Description |
|----------|-------------|
| `client.projects` | Create and manage projects |
| `client.execute()` | Run AI tasks with live streaming |
| `client.files` | Upload and download files |
| `client.artifacts` | Export structured AI outputs (xlsx, csv, json) |
| `client.threads` | View execution history |
| `client.tasks` | Manage to-do items |
| `client.integrations` | Connect external services (Gmail, LinkedIn, etc.) |
| `client.triggers` | Schedule recurring AI tasks |
| `client.billing` | Manage plans and credits |
| `client.api_keys` | Manage API keys |

## CLI

```bash
# Authenticate
starnus auth login

# Run a task
starnus run --project <project_id> "Find 10 fintech leads in Germany"

# List artifacts
starnus artifacts list --project <project_id>

# Export an artifact
starnus artifacts export <artifact_id> --format xlsx --output leads.xlsx
```

## License

MIT — see [LICENSE](LICENSE)
