miraj 0.1.0a1

Multi-cloud operational abstraction SDK

Rosetta

Rosetta is a Python SDK for multi-cloud object storage operations. It provides a single operational interface for AWS S3 and Google Cloud Storage, while keeping provider-specific SDK details, authentication behavior, and exception handling inside provider adapters.

Rosetta is intentionally narrow in scope. The MVP focuses on object storage because it is the smallest useful surface for proving cross-cloud operational abstraction without drifting into orchestration, provisioning, or control-plane complexity.

Project overview

Modern platform teams usually end up writing separate automation for each cloud provider. AWS scripts use boto3 and AWS-native patterns; GCP scripts use google-cloud-storage and GCP-native patterns. That duplication creates repeated auth setup, repeated error handling, repeated logging, and repeated operational logic.

Rosetta addresses that problem by standardizing storage operations behind one SDK interface. Application code calls Rosetta once, and Rosetta routes the operation to the correct provider adapter internally.

The design goal is operational simplicity, not fake uniformity. Rosetta standardizes the workflow, but it does not pretend AWS and GCP are identical.

Problem statement

Cloud teams commonly need the same operational actions across providers:

• upload an object
• download an object
• delete an object
• list objects
• check whether an object exists
• generate a signed URL
• create or delete a bucket

The problem is not the lack of cloud SDKs. The problem is that every provider implements these actions with different clients, auth chains, exceptions, and edge cases. That makes customer automation harder to maintain and harder to standardize.

Rosetta exists to remove that friction by providing one operational contract for the common object-storage workflow.

Architectural philosophy

Rosetta is built around these rules:

• abstract operations, not resource graphs
• keep provider-specific logic inside adapters
• normalize exceptions into stable Rosetta exceptions
• return typed models instead of raw provider dictionaries
• keep the public API small and explicit
• prefer deterministic behavior over guessing
• keep the SDK sync-first for operational scripting
• preserve the ability to extend into other services later without redesigning the core

The important boundary is this: application code should not know whether the backend is boto3 or google-cloud-storage. It should only know how to call Rosetta.

Supported providers

The MVP supports:

• AWS S3
• Google Cloud Storage

Provider support is implemented through adapter classes under src/miraj/providers/.

Supported operations

The current object-storage API supports:

• put_object
• upload_file (compatibility wrapper)
• get_object
• download_file (compatibility wrapper)
• delete_object
• delete_file (compatibility wrapper)
• object_exists
• list_objects
• copy_object
• move_object
• bulk_delete_objects
• create_bucket
• delete_bucket
• list_buckets
• generate_signed_url

For signed URLs, the MVP supports GET and PUT.

Installation

Rosetta is a normal Python package. The project is built with hatchling and managed locally with uv.

Install editable mode during development:

uv pip install -e .

Install development dependencies:

uv pip install -e ".[dev]"

Configuration

Rosetta separates provider state from provider runtime configuration.

Provider state

Provider selection is managed by Rosetta itself. The current active provider is stored in .miraj/state.json and is controlled through the CLI.

Example:

miraj set provider --gcp
miraj list providers

Provider runtime configuration

Provider-specific runtime settings live in examples/config.py during the MVP. That file holds the configuration values required by each provider.

Typical values are:

• GCP: credentials_path, project
• AWS: region, optional static credentials, or environment-based auth

The configuration file is not the provider selector. It only stores provider settings.

Provider-state workflow

Rosetta uses a simple context model:

1. the user sets the active provider through the CLI
2. Rosetta stores that selection in .miraj/state.json
3. application code calls Storage() or Storage(config=...)
4. Rosetta resolves the active provider from state
5. Rosetta initializes the correct provider adapter
6. the adapter executes the operation using the provider-native SDK

This allows the same application script to run against AWS or GCP without rewriting the script itself.

The active provider can be shown with:

miraj list providers

The current provider is marked with *.

Quickstart examples

1. Set the active provider

miraj set provider --gcp

or

miraj set provider --aws

2. Verify the selected provider

miraj list providers

3. Use Rosetta in application code

from pathlib import Path

from miraj import Storage
from config import STORAGE_CONFIG

storage = Storage(config=STORAGE_CONFIG)
content = storage.get_object(
    bucket="wmg-invoice-data",
    key="wmg invoices/WMG Invoice 2024-09-01 — 2024-09-30.csv",
)
Path("downloaded-object.csv").write_bytes(content)

4. Upload an object

from miraj import Storage
from config import STORAGE_CONFIG

storage = Storage(config=STORAGE_CONFIG)
storage.put_object(
    bucket="wmg-invoice-data",
    key="hello.txt",
    data="hello from miraj",
)

Testing instructions

The MVP was validated through direct example scripts rather than a large test harness.

Recommended checks:

• miraj list providers
• GCP object read flow
• GCP object write flow
• AWS object read flow
• AWS bucket creation flow
• object listing flow
• signed URL generation

Run the example scripts from the examples/ directory after selecting the target provider through the CLI.

Example:

miraj set provider --gcp
python examples/test_gcp_test_object_storage.py
python examples/test_gcp_put_object.py

Example AWS flow:

miraj set provider --aws
python examples/test_s3_get_object.py
python examples/test_s3_put_object.py
python examples/test_s3_create_bucket.py

Validation summary

The MVP proved the following:

• Rosetta can route calls through one SDK interface
• provider state can be set and listed through the CLI
• GCP object read and list operations work through Rosetta
• GCP upload calls are normalized through Rosetta exceptions when permissions are missing
• AWS provider initialization and request routing are wired through Rosetta
• AWS bucket creation and object operations follow the Rosetta interface
• provider-specific errors are surfaced as Rosetta exceptions rather than raw provider exceptions

Live validation depends on the customer’s own cloud credentials, IAM permissions, bucket existence, and region/project settings.

Known limitations

This MVP does not attempt to solve everything that cloud storage can do.

Current limitations include:

• only AWS S3 and Google Cloud Storage are supported
• only object storage is implemented
• no IAM abstraction
• no networking abstraction
• no provisioning or reconciliation layer
• no workflow orchestration
• no async public API yet
• no automatic provider guessing from resource names
• no deep control-plane abstraction
• no support for all advanced provider-specific features through the public API

Some capabilities remain intentionally inside the native provider escape hatches rather than the Rosetta public surface.

Future extensibility overview

Rosetta was designed so that additional services can be added without replacing the core architecture.

The extension pattern is:

1. define a public service facade
2. define a provider contract for that service
3. implement AWS and GCP adapters for the new service
4. normalize exceptions and return models
5. add contract tests
6. add example scripts

This approach is meant to make future services like EC2 / Compute Engine, SQS / Pub/Sub, or CloudWatch Logs / Cloud Logging feasible without changing how application code is written.

The important rule is to keep the public API operational and explicit. New services should follow the same pattern as storage: stable facade, provider adapters, normalized errors, typed results.

Maintenance ownership boundary

This MVP was delivered as the foundation for the customer’s internal use.

After handoff:

• the customer owns ongoing maintenance
• the customer owns cloud credentials and IAM permissions
• the customer owns environment setup for AWS and GCP
• the customer owns future service expansion unless separately agreed otherwise
• the customer owns changes to operational policy, bucket access, and runtime configuration

The intent of the handoff is to provide a working, understandable starting point that the customer can continue to extend.

Repository layout

Key files in the MVP:

• src/miraj/storage.py — public SDK facade
• src/miraj/context.py — active provider state storage and resolution
• src/miraj/cli.py — CLI for provider selection and listing
• src/miraj/exceptions.py — normalized exception hierarchy
• src/miraj/models.py — typed return models
• src/miraj/providers/aws.py — AWS S3 adapter
• src/miraj/providers/gcp.py — GCS adapter
• examples/config.py — provider runtime config used by example scripts
• examples/ — customer-facing usage examples

Notes for the customer

Rosetta is intentionally small at the MVP stage. The value is not in breadth of services. The value is in proving that one operational interface can drive multiple clouds cleanly, with provider-specific behavior isolated behind adapters and a stable SDK boundary.