miraj 0.1.0a1__tar.gz

miraj-0.1.0a1/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+.venv/
+dist/
+build/
+*.pyc
+war-key.json
+.miraj/
+invoice.csv
+downloaded-object
+hello.txt
+s3-download.csv

miraj-0.1.0a1/.rosetta/state.json

@@ -0,0 +1,5 @@
+{
+  "active_provider": "gcp"
+}
+
+# CAN BE AWS INSTEAD OF GCP

miraj-0.1.0a1/PKG-INFO

@@ -0,0 +1,331 @@
+Metadata-Version: 2.4
+Name: miraj
+Version: 0.1.0a1
+Summary: Multi-cloud operational abstraction SDK
+Project-URL: Homepage, https://github.com/<your-github-username>/miraj
+Project-URL: Repository, https://github.com/<your-github-username>/miraj
+Project-URL: Issues, https://github.com/<your-github-username>/miraj/issues
+Author: Abul Hasan
+License-Expression: MIT
+Keywords: aws,cloud,gcp,multicloud,sdk,storage
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Requires-Dist: boto3>=1.34.0
+Requires-Dist: botocore>=1.34.0
+Requires-Dist: google-cloud-storage>=2.16.0
+Requires-Dist: pyyaml>=6.0.0
+Provides-Extra: dev
+Requires-Dist: pyright>=1.1.409; extra == 'dev'
+Requires-Dist: pytest>=9.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.15.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# 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:
+
+```bash
+uv pip install -e .
+```
+
+Install development dependencies:
+
+```bash
+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:
+
+```bash
+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:
+
+```bash
+miraj list providers
+```
+
+The current provider is marked with `*`.
+
+## Quickstart examples
+
+### 1. Set the active provider
+
+```bash
+miraj set provider --gcp
+```
+
+or
+
+```bash
+miraj set provider --aws
+```
+
+### 2. Verify the selected provider
+
+```bash
+miraj list providers
+```
+
+### 3. Use Rosetta in application code
+
+```python
+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
+
+```python
+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:
+
+```bash
+miraj set provider --gcp
+python examples/test_gcp_test_object_storage.py
+python examples/test_gcp_put_object.py
+```
+
+Example AWS flow:
+
+```bash
+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.

miraj-0.1.0a1/README.md

@@ -0,0 +1,303 @@
+# 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:
+
+```bash
+uv pip install -e .
+```
+
+Install development dependencies:
+
+```bash
+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:
+
+```bash
+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:
+
+```bash
+miraj list providers
+```
+
+The current provider is marked with `*`.
+
+## Quickstart examples
+
+### 1. Set the active provider
+
+```bash
+miraj set provider --gcp
+```
+
+or
+
+```bash
+miraj set provider --aws
+```
+
+### 2. Verify the selected provider
+
+```bash
+miraj list providers
+```
+
+### 3. Use Rosetta in application code
+
+```python
+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
+
+```python
+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:
+
+```bash
+miraj set provider --gcp
+python examples/test_gcp_test_object_storage.py
+python examples/test_gcp_put_object.py
+```
+
+Example AWS flow:
+
+```bash
+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.