Metadata-Version: 2.4
Name: cloudwright-ai
Version: 0.2.0
Summary: Architecture intelligence for cloud engineers — design, cost, compare, export
Project-URL: Homepage, https://github.com/xmpuspus/cloudwright
Project-URL: Repository, https://github.com/xmpuspus/cloudwright
Project-URL: Issues, https://github.com/xmpuspus/cloudwright/issues
Author: Xavier Puspus
License-Expression: MIT
Keywords: architecture,aws,azure,cloud,gcp,iac,infrastructure,terraform
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.12
Requires-Dist: anthropic<1,>=0.58
Requires-Dist: openai<3,>=1.50
Requires-Dist: pydantic<3,>=2.11
Requires-Dist: pyyaml<7,>=6.0
Provides-Extra: cli
Requires-Dist: cloudwright-ai-cli; extra == 'cli'
Provides-Extra: pdf
Requires-Dist: markdown2; extra == 'pdf'
Requires-Dist: weasyprint; extra == 'pdf'
Provides-Extra: web
Requires-Dist: cloudwright-ai-web; extra == 'web'
Description-Content-Type: text/markdown

# Cloudwright

Architecture intelligence for cloud engineers.

Cloudwright bridges the gap between a whiteboard sketch and deployable infrastructure. Describe a system in natural language, and Cloudwright produces a structured architecture spec, cost estimates, compliance reports, Terraform/CloudFormation code, diagrams, and diffs — all from a single format called **ArchSpec**.

```
"HIPAA-compliant 3-tier app on AWS, budget $3k/month"
    │
    ▼
┌────────────────────────────────────────────────┐
│  ArchSpec (YAML)                               │
│  ├── 8 components (ALB, ECS, RDS, S3, ...)    │
│  ├── connections with protocols                │
│  └── constraints: hipaa, budget: 3000          │
└────────┬───────────┬──────────┬────────────────┘
         │           │          │
    ┌────▼───┐  ┌───▼────┐ ┌──▼──────────┐
    │  Cost  │  │Validate│ │   Export     │
    │$2,847  │  │ HIPAA  │ │ Terraform   │
    │  /mo   │  │ 5/5    │ │ CFN, Mermaid│
    └────────┘  └────────┘ └─────────────┘
```

## Why Cloudwright

Most cloud tooling assumes you already know what to build (IaC) or already have it deployed (cost dashboards, security scanners). Cloudwright operates in the design phase — the gap where architects currently rely on tribal knowledge, ad-hoc spreadsheets, and copy-pasting last quarter's Terraform.

**One spec, many outputs.** ArchSpec is the universal interchange format. Every module — design, cost, compliance, export, diff, lint, score — reads and writes it. No glue code, no format conversion.

### How it compares

| Capability | Cloudwright | Terraform | Pulumi Neo | Brainboard | Infracost | Checkov |
|---|:---:|:---:|:---:|:---:|:---:|:---:|
| NL to architecture | Y | - | Y | Y | - | - |
| IaC generation | TF + CFN | HCL | Code | TF | - | - |
| Cost estimation | Y (design-time) | - | - | Basic | Y (code-time) | - |
| Compliance validation | 6 frameworks | - | OPA policies | - | - | 2500+ rules |
| Architecture diffing | Y | Plan diff | Preview diff | Drift | Cost diff | - |
| Diagram export | Mermaid + D2 | - | - | Y | - | - |
| SBOM / AIBOM | Y | - | - | - | - | - |
| Multi-cloud | AWS/GCP/Azure | All | All | AWS/GCP/Azure/OCI | AWS/GCP/Azure | All |
| Open source | Y | BSL / OpenTofu | Engine only | - | CLI only | Y |
| Runs locally | Y | Y | Y | - | Y | Y |

Terraform and Infracost are deployment/cost tools that sit *downstream* — Cloudwright generates the Terraform code and estimates costs before any code exists. Checkov and Prowler scan *after* code is written; Cloudwright validates at design time. Brainboard is the closest direct competitor (NL-to-arch + TF), but it's SaaS-only and doesn't do compliance or cost estimation.

Full competitor analysis covering 30 tools across IaC, cost, compliance, and diagramming: [competitor-landscape.md](docs/competitor-landscape.md)

## Quick Start

```bash
pip install cloudwright[cli]
```

Set an LLM provider key:

```bash
export ANTHROPIC_API_KEY=sk-ant-...
# or
export OPENAI_API_KEY=sk-...
```

```bash
# Design from natural language
cloudwright design "3-tier web app on AWS with Redis and PostgreSQL"

# Estimate cost
cloudwright cost spec.yaml

# Validate compliance
cloudwright validate spec.yaml --compliance hipaa,soc2

# Export Terraform
cloudwright export spec.yaml --format terraform -o ./infra

# Compare cost across clouds
cloudwright cost spec.yaml --compare gcp,azure

# Interactive multi-turn design
cloudwright chat
```

## Features

### Architecture Design

LLM-powered architecture generation from plain English. Supports multi-turn conversation, constraint-aware design, and natural language modification of existing specs.

```bash
cloudwright design "Serverless data pipeline on GCP with Pub/Sub, Dataflow, and BigQuery" \
  --provider gcp --budget 2000 --compliance gdpr

cloudwright modify spec.yaml "Add a Redis cache between the API and database"

cloudwright chat  # interactive mode with /save, /cost, /export commands
```

100 service keys across three clouds:
- **AWS** (47): EC2, ECS, EKS, Lambda, RDS, Aurora, DynamoDB, S3, SQS, SNS, Kinesis, Redshift, SageMaker, KMS, GuardDuty, CloudTrail, and more
- **GCP** (25): Compute Engine, GKE, Cloud Run, Cloud SQL, Spanner, BigQuery, Pub/Sub, Vertex AI, Cloud Build, and more
- **Azure** (28): Virtual Machines, AKS, Azure Functions, Azure SQL, Cosmos DB, Synapse, Azure ML, Azure Sentinel, and more

The architect applies safe defaults automatically: encryption on data stores, backups on databases, multi-AZ on production workloads, auto-scaling on compute.

### Cost Estimation

Per-component monthly pricing from a built-in SQLite catalog. No external API calls, no rate limits. Supports four pricing tiers.

```bash
cloudwright cost spec.yaml                              # on-demand pricing
cloudwright cost spec.yaml --pricing-tier reserved_1yr  # 1-year reserved
cloudwright cost spec.yaml --compare gcp,azure          # multi-cloud comparison
```

The cost engine resolves prices through three tiers: catalog database (instance-level pricing), registry formula dispatch (10 named formulas for serverless/managed services), and static fallback table (90+ service defaults). Data transfer costs are calculated separately with per-provider egress rates.

Pricing tiers: `on_demand` (1.0x), `reserved_1yr` (0.6x), `reserved_3yr` (0.4x), `spot` (0.3x).

### Compliance Validation

Six compliance frameworks with 35 individual checks:

| Framework | Checks | Key Validations |
|---|---|---|
| HIPAA | 5 | Encryption at rest/transit, audit logging, access control, BAA eligibility |
| PCI-DSS | 5 | WAF, network segmentation, encryption, TLS 1.2+, audit trail |
| SOC 2 | 5 | Logging, access controls, encryption, availability, change management |
| FedRAMP Moderate | 7 | FIPS 140-2, US regions, MFA, audit logging, continuous monitoring |
| GDPR | 6 | EU data residency, encryption, access controls, audit trail, data deletion |
| Well-Architected | 7 | Multi-AZ, auto-scaling, backup, monitoring, SPOF detection, cost optimization |

```bash
cloudwright validate spec.yaml --compliance hipaa,pci-dss,soc2
cloudwright validate spec.yaml --well-architected
cloudwright validate spec.yaml --compliance fedramp --report audit-report.md
```

Exit code 1 on failures, making it CI-friendly.

### Infrastructure Export

Seven export formats from a single ArchSpec:

| Format | Flag | Description |
|---|---|---|
| Terraform HCL | `terraform` | Provider-native resources for AWS (24 types), GCP (11), Azure (10) |
| CloudFormation | `cloudformation` | YAML template with Parameters and Outputs |
| Mermaid | `mermaid` | Tier-grouped flowchart for docs and GitHub |
| D2 | `d2` | D2 diagram language with provider badges |
| CycloneDX SBOM | `sbom` | CycloneDX 1.5 service bill of materials |
| OWASP AIBOM | `aibom` | AI bill of materials documenting LLM usage and risks |
| Compliance Report | `compliance` | Audit-ready markdown with check details and evidence |

```bash
cloudwright export spec.yaml --format terraform -o ./infra
cloudwright export spec.yaml --format mermaid
cloudwright export spec.yaml --format sbom -o sbom.json
```

Terraform output uses variables for sensitive values (no hardcoded passwords or ARNs), includes provider blocks with region configuration, and generates data sources for VPC/subnet discovery.

### Architecture Diffing

Structured comparison between two ArchSpec versions with component-level changes, cost delta, and compliance impact assessment.

```bash
cloudwright diff v1.yaml v2.yaml
```

Detects: added/removed components, changed configurations, connection changes (added/removed/modified), cost impact, and security implications (removal of WAF, encryption changes, auth service changes).

### Multi-Cloud Comparison

Maps equivalent services across providers using 22 cross-cloud equivalence pairs:

```
ec2 <-> compute_engine <-> virtual_machines
rds <-> cloud_sql <-> azure_sql
s3  <-> cloud_storage <-> blob_storage
eks <-> gke <-> aks
...
```

```bash
cloudwright compare spec.yaml --providers gcp,azure
```

Shows side-by-side service mapping with monthly cost totals per provider.

### Architecture Linter

10 anti-pattern checks:

```bash
cloudwright lint spec.yaml
cloudwright lint spec.yaml --strict  # fail on warnings too
```

Errors: unencrypted data stores, single-AZ databases, missing load balancer, public databases, single point of failure.
Warnings: oversized instances (16xlarge+), missing WAF, missing monitoring, missing backups, missing auth.

### Architecture Scorer

Five-dimension quality scoring (0-100, letter grade):

```bash
cloudwright score spec.yaml --with-cost
```

- **Reliability** (30%): load balancing, multi-AZ, auto-scaling, CDN, caching
- **Security** (25%): WAF, auth, encryption, HTTPS, DNS management
- **Cost Efficiency** (20%): budget compliance, per-component ratio, free tier usage
- **Compliance** (15%): framework validation score
- **Complexity** (10%): component count, connection density, tier separation

Grades: A (90+), B (80+), C (70+), D (60+), F (<60).

### Blast Radius Analysis

Dependency graph analysis with SPOF detection and critical path identification.

```bash
cloudwright analyze spec.yaml
cloudwright analyze spec.yaml --component api_gateway  # focus on one component
```

For each component: direct dependents, transitive dependents, blast radius, SPOF status, and tier position.

### Drift Detection

Compares architecture spec against deployed infrastructure.

```bash
cloudwright drift spec.yaml terraform.tfstate
cloudwright drift spec.yaml cloudformation-template.yaml
```

Produces a drift score (0.0-1.0) with lists of drifted, extra, and missing components.

### Policy Engine

Policy-as-code via YAML rules. Nine built-in checks: max_components, all_encrypted, require_multi_az, budget_monthly, no_banned_services, required_tags, min_redundancy, allowed_providers, allowed_regions.

```yaml
# policy.yaml
rules:
  - name: enforce-encryption
    check: all_encrypted
    severity: deny
  - name: budget-cap
    check: budget_monthly
    value: 10000
    severity: deny
  - name: no-azure
    check: allowed_providers
    value: [aws, gcp]
    severity: warn
```

```bash
cloudwright policy spec.yaml --rules policy.yaml
```

Severity levels: `deny` (exit code 1), `warn`, `info`.

### Infrastructure Import

Import existing infrastructure into ArchSpec format:

```bash
cloudwright import terraform.tfstate -o spec.yaml
cloudwright import cloudformation-template.yaml -o spec.yaml
```

Auto-detects format from file extension and content. Plugin support for custom importers via the `cloudwright.importers` entry point.

### Templates

14 starter architectures across three providers:

```bash
cloudwright init --list                              # show available templates
cloudwright init --template serverless_api           # AWS API Gateway + Lambda + DynamoDB
cloudwright init --template gcp_microservices -o .   # GKE + service mesh
cloudwright init --project                           # create .cloudwright/ project directory
```

**AWS** (8): three_tier_web, serverless_api, ml_pipeline, data_lake, event_driven, static_site, microservices, batch_processing.
**GCP** (3): three_tier_web, serverless_api, microservices.
**Azure** (3): three_tier_web, serverless_api, microservices.

### Web UI

FastAPI backend + React frontend for browser-based architecture design.

```bash
pip install cloudwright[web]
cloudwright chat --web
```

10 API endpoints: design, modify, cost, validate, export, diff, catalog search, catalog compare, chat, health.

### Plugin System

Four extension points via Python entry points:

- `cloudwright.exporters` — custom export formats
- `cloudwright.validators` — custom compliance frameworks
- `cloudwright.policies` — custom policy checks
- `cloudwright.importers` — custom infrastructure importers

```bash
cloudwright --list-plugins  # discover installed plugins
```

## ArchSpec Format

ArchSpec is plain YAML, human-editable, and version-controllable alongside code.

```yaml
name: healthcare-portal
version: 1
provider: aws
region: us-east-1

constraints:
  compliance: [hipaa]
  budget_monthly: 5000
  availability: 99.9

components:
  - id: alb
    service: alb
    provider: aws
    label: Application Load Balancer
    tier: 1

  - id: api
    service: ecs
    provider: aws
    label: API Service
    tier: 2
    config:
      launch_type: FARGATE
      cpu: 512
      memory: 1024
      desired_count: 2

  - id: db
    service: rds
    provider: aws
    label: PostgreSQL
    tier: 3
    config:
      engine: postgresql
      instance_class: db.r5.large
      multi_az: true
      encryption: true
      storage_gb: 100

connections:
  - source: alb
    target: api
    protocol: https
    port: 443
  - source: api
    target: db
    protocol: tcp
    port: 5432
```

Components use a 5-tier system for vertical positioning: Edge (0), Ingress (1), Compute (2), Data (3), Storage/Analytics (4).

## CLI Reference

| Command | Description |
|---|---|
| `design <prompt>` | Generate ArchSpec from natural language |
| `modify <spec> <instruction>` | Modify existing spec with natural language |
| `cost <spec>` | Monthly cost breakdown with optional `--compare`, `--pricing-tier` |
| `compare <spec>` | Multi-cloud service mapping and cost comparison |
| `validate <spec>` | Compliance checks with `--compliance`, `--well-architected`, `--report` |
| `export <spec>` | Export to IaC/diagram/SBOM with `--format`, `--output` |
| `diff <spec_a> <spec_b>` | Structured diff with cost delta and compliance impact |
| `import <source>` | Import from Terraform state or CloudFormation |
| `chat` | Interactive multi-turn design session (`--web` for browser UI) |
| `init` | Initialize from template with `--template`, `--project` |
| `lint <spec>` | Anti-pattern detection (`--strict` fails on warnings) |
| `score <spec>` | Quality scoring across 5 dimensions (`--with-cost`) |
| `analyze <spec>` | Blast radius and SPOF detection (`--component` for focus) |
| `drift <spec> <infra>` | Compare design vs deployed infrastructure |
| `policy <spec>` | Evaluate policy rules from YAML (`--rules`) |
| `refresh` | Update catalog pricing data (`--provider`, `--dry-run`) |
| `catalog search <query>` | Search instance catalog by specs |
| `catalog compare <a> <b>` | Side-by-side instance comparison |

Global flags: `--json`, `--verbose / -v`, `--version / -V`.

## Python API

```python
from pathlib import Path
from cloudwright import ArchSpec
from cloudwright.cost import CostEngine
from cloudwright.validator import Validator
from cloudwright.exporter import export_spec
from cloudwright.differ import diff_specs
from cloudwright.linter import lint
from cloudwright.scorer import Scorer

spec = ArchSpec.from_file("spec.yaml")

# Cost
engine = CostEngine()
priced = engine.price(spec)
for item in priced.cost_estimate.breakdown:
    print(f"{item.component_id}: ${item.monthly:,.2f}/mo")

# Compliance
validator = Validator()
results = validator.validate(spec, compliance=["hipaa", "pci-dss"])

# Export
hcl = export_spec(spec, "terraform", output_dir="./infra")
diagram = export_spec(spec, "mermaid")

# Diff
old = ArchSpec.from_file("v1.yaml")
new = ArchSpec.from_file("v2.yaml")
diff = diff_specs(old, new)

# Lint
findings = lint(spec)

# Score
scorer = Scorer()
report = scorer.score(spec)
print(f"Grade: {report.grade} ({report.overall:.0f}/100)")
```

## Service Catalog

Ships as a SQLite database bundled with the package. No network calls required.

- Compute, database, networking, and storage pricing for AWS, GCP, and Azure
- 4 pricing tiers (on-demand, reserved 1yr/3yr, spot)
- Cross-cloud instance equivalences with confidence scores
- 22 service-level equivalence pairs for multi-cloud mapping
- 10 named pricing formulas for managed/serverless services
- 90+ static fallback prices for less common services

```bash
cloudwright catalog search "8 vcpu 32gb memory"
cloudwright catalog compare m5.xlarge n2-standard-4 Standard_D4s_v5
```

## Benchmarks

Evaluated against raw Claude (Sonnet 4.6) across 54 use cases spanning greenfield, compliance, cost optimization, import, microservices, data pipelines, industry-specific, migration, edge computing, and cross-cloud comparison scenarios.

| Metric | Cloudwright | Claude (raw) | Delta |
|---|---|---|---|
| Structural Validity | 79.6% | 37.0% | +42.6 |
| Compliance Completeness | 62.9% | 38.5% | +24.3 |
| Export Quality (IaC) | 55.7% | 0.3% | +55.5 |
| Diff Capability | 100.0% | 0.0% | +100.0 |
| Reproducibility | 77.9% | 35.0% | +42.9 |
| Time to IaC | 82.5% | 0.0% | +82.5 |
| **Overall** | **68.1%** | **28.0%** | **+40.1** |

Cloudwright wins 6 of 8 metrics. Weakest areas (active development): cost accuracy and service correctness on import/migration use cases.

Full results: [benchmark/results/benchmark_report.md](benchmark/results/benchmark_report.md)

## Repository Structure

```
cloudwright/
  packages/
    core/       pip install cloudwright          Models, architect, catalog, cost, validators, exporters
    cli/        pip install cloudwright[cli]     Typer CLI with Rich formatting
    web/        pip install cloudwright[web]     FastAPI + React web UI
  catalog/                                      Service catalog JSON (compute, database, storage, networking)
  benchmark/                                    54 use cases + evaluation framework
```

## Development

```bash
git clone https://github.com/theAtticAI/cloudwright
pip install -e packages/core
pip install -e packages/cli
pip install -e packages/web
```

```bash
pytest packages/core/tests/           # 689 tests
ruff check packages/ && ruff format packages/
```

LLM-dependent tests (architect, chat) require an API key and are skipped by default:

```bash
ANTHROPIC_API_KEY=sk-ant-... pytest packages/core/tests/test_architect.py -v
```

## License

MIT
