Metadata-Version: 2.4
Name: lamia-cloud
Version: 0.3.1
Summary: Cloud execution backend for Lamia: run once with --remote, schedule jobs, and with cloud triggers.
Author: Sergey Sargsyan
License: MIT License
        
        Copyright (c) 2026 Sergey Sargsyan
        
        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.
        
Project-URL: Homepage, https://github.com/lamia-lang/lamia-cloud
Project-URL: Repository, https://github.com/lamia-lang/lamia-cloud
Project-URL: Issues, https://github.com/lamia-lang/lamia-cloud/issues
Keywords: lamia,llm,agentic automation,cloud scheduler,gcp,serverless,workflow automation,python automation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT 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: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: lamia-lang>=0.1.0
Requires-Dist: google-cloud-scheduler>=2.13.0
Requires-Dist: google-cloud-build>=3.20.0
Requires-Dist: google-cloud-run>=0.10.0
Requires-Dist: google-cloud-storage>=2.14.0
Requires-Dist: google-cloud-service-usage>=1.8.0
Requires-Dist: google-cloud-iam>=2.16.0
Requires-Dist: google-cloud-resource-manager>=1.3.0
Requires-Dist: google-cloud-logging>=3.8.0
Requires-Dist: google-cloud-eventarc>=1.11.0
Requires-Dist: google-cloud-monitoring>=2.16.0
Requires-Dist: google-cloud-workflows>=1.14.0
Requires-Dist: google-cloud-pubsub>=2.19.0
Requires-Dist: pyyaml>=6.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.18.0; extra == "dev"
Dynamic: license-file

# lamia-cloud

Cloud execution backend for [Lamia](https://github.com/lamia-lang/lamia). Run `.lm` scripts once with `--remote`, deploy scheduled cloud jobs, and prepare for upcoming cloud trigger support. Currently supports GCP.

For common agent use cases, you usually do not need to build custom cloud-agent infrastructure from scratch before shipping with Lamia.

## Installation

```bash
pip install "lamia-lang[cloud]"
```

## Prerequisites

- GCP project with billing enabled
- Application Default Credentials: `gcloud auth application-default login`

All required GCP APIs (including Service Usage) are enabled automatically on first deploy.

## Quick Start

1. Add a `cloud` section to your project's `config.yaml`:

```yaml
cloud:
  provider: gcp
  project_id: my-gcp-project
  location: us-central1  # optional, default: us-central1
```

2. Run a script once in the cloud with `--remote`:

```bash
lamia my_script.lm --remote
```

Use this one-shot run to validate cloud execution, permissions, and logs before adding a schedule.

3. Schedule your script with the `--remote` flag:

```bash
lamia schedule add my_script.lm --every day --remote
```

The `--remote` flag tells lamia to deploy and run the script in the cloud instead of locally.

## Managing Schedules

```bash
lamia schedule list              # shows all jobs (local + cloud) with live status
lamia schedule add X --remote    # deploy and schedule a new cloud job
lamia schedule remove <id>       # tears down cloud resources and removes the job
```

## How It Works

1. `lamia <script>.lm --remote` packages your project and runs it as a Cloud Run Job (one-shot)
2. `lamia schedule add <script>.lm --remote` deploys the same cloud job with Cloud Scheduler
3. Cloud Scheduler triggers the job on your cron schedule
4. Logs are available in Cloud Logging
5. `lamia schedule list` fetches live execution status from the cloud

## LLM on Cloud — Vertex AI

Scripts that use LLM calls run through **Vertex AI** on cloud. This gives you:

- **No API keys** — authentication via IAM, no keys to store, rotate, or leak
- **Budget control** — Vertex AI quotas and billing alerts
- **Secure by default** — no API key transport or storage, traffic stays within GCP

### Supported Models

| Provider | Cloud routing |
|----------|--------------|
| **Anthropic** (Claude) | Runs natively on Vertex AI — same models, same quality |
| **Google** (Gemini) | Runs natively on Vertex AI |
| **OpenAI** (GPT, o-series) | Automatically mapped to Gemini by tier (strong/medium/light) with runtime selection of the best available current Gemini model |

Anthropic and Google models run as-is. OpenAI models are mapped because they're not available on Vertex AI — tier classification is stable while the selected Gemini model is discovered dynamically at runtime.

## Configuration Reference

| Field | Required | Default | Description |
|-------|----------|---------|-------------|
| `cloud.provider` | Yes | — | Cloud provider (currently `gcp`) |
| `cloud.project_id` | Yes | — | Your GCP project ID |
| `cloud.location` | No | `us-central1` | Region for Cloud Run deployment |

No environment variables are required.

## Troubleshooting

- If Vertex AI access is not enabled yet, lamia-cloud logs a project-specific URL and attempts to open it automatically in your browser:
  `https://console.cloud.google.com/vertex-ai?project=<your-project-id>`
- After accepting terms, re-run the schedule/install command once.

## CI Authentication

Repository connection and CI authentication are managed by `lamia cloud connect`. For the security architecture and design decisions, see [src/gcp/README.md](src/gcp/README.md#repository-connection--security-architecture).

## Development

```bash
git clone https://github.com/lamia-lang/lamia-cloud.git
cd lamia-cloud
pip install -e ".[dev]"
pytest
```

## Releasing

```bash
git tag v0.1.0
git push origin v0.1.0
```
