starnus 1.0.0__tar.gz

starnus-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Starnus Technologies B.V.
+
+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.

starnus-1.0.0/PKG-INFO

@@ -0,0 +1,142 @@
+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)

starnus-1.0.0/README.md

@@ -0,0 +1,103 @@
+# 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)

starnus-1.0.0/pyproject.toml

@@ -0,0 +1,79 @@
+[build-system]
+requires = ["setuptools>=65.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "starnus"
+version = "1.0.0"
+description = "Official Python SDK and CLI for the Starnus AI platform"
+readme = "README.md"
+requires-python = ">=3.9"
+license = {text = "MIT"}
+authors = [
+    {name = "Starnus Team", email = "support@starnustech.com"}
+]
+keywords = ["starnus", "ai", "sdk", "automation", "agents", "cli"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+# Core consumer SDK deps — minimal footprint
+dependencies = [
+    "requests>=2.31.0",
+    "websocket-client>=1.7.0",
+    "click>=8.1.0",
+]
+
+[project.optional-dependencies]
+# Optional: DataFrame integration for artifact import/export
+pandas = ["pandas>=2.0.0", "openpyxl>=3.1.0"]
+
+# All optional extras combined
+all = [
+    "pandas>=2.0.0",
+    "openpyxl>=3.1.0",
+]
+
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+    "responses>=0.25.0",
+    "ruff>=0.3.0",
+    "mypy>=1.8.0",
+    "types-requests>=2.31.0",
+]
+
+[project.urls]
+Homepage = "https://starnus.com"
+Documentation = "https://docs.starnus.com"
+
+[project.scripts]
+starnus = "starnus_sdk.cli.main:cli"
+
+# v1 ships without the component (agent-deploy) subsystem.
+# Explicitly list only the packages to distribute.
+[tool.setuptools]
+packages = [
+    "starnus_sdk",
+    "starnus_sdk.cli",
+    "starnus_sdk.framework",
+    "starnus_sdk.models",
+    "starnus_sdk.resources",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+asyncio_mode = "auto"

starnus-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

starnus-1.0.0/starnus.egg-info/PKG-INFO

@@ -0,0 +1,142 @@
+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)

starnus-1.0.0/starnus.egg-info/SOURCES.txt

@@ -0,0 +1,58 @@
+LICENSE
+README.md
+pyproject.toml
+starnus.egg-info/PKG-INFO
+starnus.egg-info/SOURCES.txt
+starnus.egg-info/dependency_links.txt
+starnus.egg-info/entry_points.txt
+starnus.egg-info/requires.txt
+starnus.egg-info/top_level.txt
+starnus_sdk/__init__.py
+starnus_sdk/_config.py
+starnus_sdk/_http.py
+starnus_sdk/_version.py
+starnus_sdk/_websocket.py
+starnus_sdk/client.py
+starnus_sdk/cli/__init__.py
+starnus_sdk/cli/api_keys_cmd.py
+starnus_sdk/cli/artifacts.py
+starnus_sdk/cli/auth.py
+starnus_sdk/cli/billing.py
+starnus_sdk/cli/chat.py
+starnus_sdk/cli/files.py
+starnus_sdk/cli/integrations.py
+starnus_sdk/cli/main.py
+starnus_sdk/cli/projects.py
+starnus_sdk/cli/run.py
+starnus_sdk/cli/tasks.py
+starnus_sdk/cli/threads.py
+starnus_sdk/cli/triggers.py
+starnus_sdk/framework/__init__.py
+starnus_sdk/models/__init__.py
+starnus_sdk/models/api_key.py
+starnus_sdk/models/artifact.py
+starnus_sdk/models/execution.py
+starnus_sdk/models/file.py
+starnus_sdk/models/integration.py
+starnus_sdk/models/plan.py
+starnus_sdk/models/profile.py
+starnus_sdk/models/project.py
+starnus_sdk/models/task.py
+starnus_sdk/models/thread.py
+starnus_sdk/models/trigger.py
+starnus_sdk/resources/__init__.py
+starnus_sdk/resources/api_keys.py
+starnus_sdk/resources/artifacts.py
+starnus_sdk/resources/billing.py
+starnus_sdk/resources/executions.py
+starnus_sdk/resources/expert.py
+starnus_sdk/resources/files.py
+starnus_sdk/resources/integrations.py
+starnus_sdk/resources/profile.py
+starnus_sdk/resources/projects.py
+starnus_sdk/resources/support.py
+starnus_sdk/resources/tasks.py
+starnus_sdk/resources/threads.py
+starnus_sdk/resources/triggers.py
+starnus_sdk/resources/updates.py
+starnus_sdk/resources/usage.py

starnus-1.0.0/starnus.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

starnus-1.0.0/starnus.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+starnus = starnus_sdk.cli.main:cli

starnus-1.0.0/starnus.egg-info/requires.txt

@@ -0,0 +1,19 @@
+requests>=2.31.0
+websocket-client>=1.7.0
+click>=8.1.0
+
+[all]
+pandas>=2.0.0
+openpyxl>=3.1.0
+
+[dev]
+pytest>=8.0.0
+pytest-asyncio>=0.23.0
+responses>=0.25.0
+ruff>=0.3.0
+mypy>=1.8.0
+types-requests>=2.31.0
+
+[pandas]
+pandas>=2.0.0
+openpyxl>=3.1.0

starnus-1.0.0/starnus.egg-info/top_level.txt

@@ -0,0 +1 @@
+starnus_sdk

starnus-1.0.0/starnus_sdk/__init__.py

@@ -0,0 +1,32 @@
+"""
+Starnus Python SDK — official client for the Starnus AI platform.
+
+Quick start:
+    from starnus_sdk import Starnus
+
+    client = Starnus(api_key="sk_live_...")   # or set STARNUS_API_KEY
+    print(client.me())
+    projects = client.projects.list()
+"""
+
+from starnus_sdk._version import __version__
+from starnus_sdk.client import Starnus
+from starnus_sdk._http import (
+    StarnusError,
+    AuthenticationError,
+    PermissionError,
+    NotFoundError,
+    RateLimitError,
+    StarnusAPIError,
+)
+
+__all__ = [
+    "Starnus",
+    "__version__",
+    "StarnusError",
+    "AuthenticationError",
+    "PermissionError",
+    "NotFoundError",
+    "RateLimitError",
+    "StarnusAPIError",
+]

starnus-1.0.0/starnus_sdk/_config.py

@@ -0,0 +1,83 @@
+"""
+Config file management for the Starnus SDK.
+
+Config stored at ~/.starnus/config.json with permissions 600.
+Directory created with permissions 700.
+
+Lookup order for api_key:
+  1. STARNUS_API_KEY environment variable
+  2. ~/.starnus/config.json
+"""
+
+import json
+import os
+import stat
+from pathlib import Path
+from typing import Optional
+
+_CONFIG_DIR = Path.home() / ".starnus"
+_CONFIG_FILE = _CONFIG_DIR / "config.json"
+
+# Supported keys
+_KNOWN_KEYS = {"api_key", "base_url", "ws_url", "default_project_id", "component_token"}
+
+
+def _ensure_config_dir() -> None:
+    """Create ~/.starnus/ with 700 permissions if it doesn't exist."""
+    _CONFIG_DIR.mkdir(exist_ok=True)
+    _CONFIG_DIR.chmod(0o700)
+
+
+def load_config() -> dict:
+    """
+    Load the config file. Returns empty dict if file doesn't exist or is malformed.
+    """
+    if not _CONFIG_FILE.exists():
+        return {}
+    try:
+        with open(_CONFIG_FILE, "r") as f:
+            data = json.load(f)
+        return {k: v for k, v in data.items() if k in _KNOWN_KEYS}
+    except (json.JSONDecodeError, OSError):
+        return {}
+
+
+def save_config(updates: dict) -> None:
+    """
+    Merge updates into the config file and write it with 600 permissions.
+    Only saves keys in _KNOWN_KEYS.
+    """
+    _ensure_config_dir()
+    current = load_config()
+    current.update({k: v for k, v in updates.items() if k in _KNOWN_KEYS and v is not None})
+    # Remove None values
+    current = {k: v for k, v in current.items() if v is not None}
+
+    with open(_CONFIG_FILE, "w") as f:
+        json.dump(current, f, indent=2)
+
+    _CONFIG_FILE.chmod(0o600)
+
+
+def delete_config() -> None:
+    """Remove the config file (logout)."""
+    if _CONFIG_FILE.exists():
+        _CONFIG_FILE.unlink()
+
+
+def get_api_key() -> Optional[str]:
+    """
+    Resolve API key from environment variable first, then config file.
+    Returns None if not set.
+    """
+    env_key = os.environ.get("STARNUS_API_KEY")
+    if env_key:
+        return env_key.strip()
+    return load_config().get("api_key")
+
+
+def get_value(key: str) -> Optional[str]:
+    """Get a single config value, checking env vars first for api_key."""
+    if key == "api_key":
+        return get_api_key()
+    return load_config().get(key)