Metadata-Version: 2.4
Name: arch-sparring-agent
Version: 0.5.3
Summary: Multi-agent architecture review system using AWS Bedrock
Project-URL: Homepage, https://github.com/michelangelo17/arch-sparring-agent
Project-URL: Documentation, https://github.com/michelangelo17/arch-sparring-agent#readme
Project-URL: Repository, https://github.com/michelangelo17/arch-sparring-agent
Project-URL: Changelog, https://github.com/michelangelo17/arch-sparring-agent/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/michelangelo17/arch-sparring-agent/issues
License: MIT
License-File: LICENSE
Keywords: agents,ai,architecture,aws,bedrock,cloudformation,review
Classifier: Development Status :: 4 - Beta
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
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.11
Requires-Dist: bedrock-agentcore-starter-toolkit>=0.1.0
Requires-Dist: bedrock-agentcore>=1.1.1
Requires-Dist: boto3>=1.42.2
Requires-Dist: click>=8.0.0
Requires-Dist: markdown>=3.10
Requires-Dist: pillow>=12.0.0
Requires-Dist: python-frontmatter>=1.1.0
Requires-Dist: strands-agents>=1.19.0
Provides-Extra: otel
Requires-Dist: strands-agents[otel]>=1.19.0; extra == 'otel'
Description-Content-Type: text/markdown

# Architecture Review Sparring Partner

Multi-agent system for architecture reviews. Analyzes requirements documents, CloudFormation templates, architecture diagrams, and source code, then challenges architectural decisions through interactive sparring.

## Features

- **5-phase review process**: Requirements → Architecture → Questions → Sparring → Final Review
- **Interactive sparring**: Challenges architectural gaps and pushes back on weak justifications
- **Remediation mode**: Discuss and resolve findings from previous reviews with session memory
- **CI/CD mode**: Non-interactive automated reviews with structured output and exit codes
- **CDK support**: Works with CloudFormation templates and CDK synthesized output (`cdk.out/`)
- **Multimodal analysis**: Analyzes architecture diagrams (PNG, JPEG) via Bedrock
- **Full session export**: Saves complete review session to markdown or JSON

## Prerequisites

- Python 3.11+
- AWS credentials configured
- Nova 2 Lite model access in Bedrock console

## Installation

```bash
pip install arch-sparring-agent
```

## Usage

### Interactive Mode (Default)

```bash
arch-review \
    --documents-dir ./docs \
    --templates-dir ./templates \
    --diagrams-dir ./diagrams
```

Outputs to `.arch-review/` folder. Previous reviews are automatically archived to `.arch-review/history/`.

### With Source Code Analysis

```bash
arch-review \
    --documents-dir ./docs \
    --templates-dir ./cdk.out \
    --diagrams-dir ./diagrams \
    --source-dir ./src/lambdas
```

### CI/CD Mode

```bash
# Non-interactive (no history archiving by default)
arch-review --ci \
    --documents-dir ./docs \
    --templates-dir ./cdk.out \
    --diagrams-dir ./diagrams

# JSON output for programmatic processing
arch-review --json \
    --documents-dir ./docs \
    --templates-dir ./templates \
    --diagrams-dir ./diagrams

# CI with history archiving
arch-review --ci --keep-history \
    --documents-dir ./docs \
    --templates-dir ./cdk.out \
    --diagrams-dir ./diagrams
```

### Remediation Mode

After running a review, discuss and resolve findings:

```bash
arch-review --remediate
```

- Loads gaps/risks from `.arch-review/state.json`
- Continues conversations across sessions via memory
- Saves notes to `.arch-review/remediation-notes.md`

### Options

| Option                    | Description                                               |
| ------------------------- | --------------------------------------------------------- |
| `--documents-dir`         | Directory with markdown requirements/constraints          |
| `--templates-dir`         | CloudFormation templates or `cdk.out/` directory          |
| `--diagrams-dir`          | Architecture diagrams (PNG, JPEG)                         |
| `--source-dir`            | Lambda/application source code (optional)                 |
| `--output-dir`            | Output directory (default: `.arch-review`)                |
| `--no-history`            | Don't archive previous reviews (default in CI mode)       |
| `--keep-history`          | Archive previous reviews even in CI mode                  |
| `--no-state`              | Don't save state file after review                        |
| `--remediate`             | Enter remediation mode                                    |
| `--no-remediation-output` | Don't save remediation notes                              |
| `--ci`                    | CI/CD mode: non-interactive analysis                      |
| `--json`                  | Output as JSON (implies --ci)                             |
| `--strict`                | Fail on any High impact risk (ignores verdict)            |
| `--reasoning-level`       | Reasoning effort: off, low, medium, high (default: low)   |
| `--skip-policy-check`     | Skip policy engine setup (development only)               |
| `-v`, `--verbose`         | Show detailed output (policy setup, debug info)           |
| `--model`                 | Model: `nova-2-lite` or `opus-4.6` (default: nova-2-lite) |
| `--region`                | AWS region (default: eu-central-1)                        |

### Supported Models

The `--model` flag accepts a short name from the curated model registry.
Only models with 1M context windows are supported to ensure reliable full-project reviews.

| Short Name      | Model                     | Context | `--model` value |
| --------------- | ------------------------- | ------- | --------------- |
| Nova 2 Lite     | Amazon Nova 2 Lite        | 1M      | `nova-2-lite`   |
| Claude Opus 4.6 | Anthropic Claude Opus 4.6 | 1M      | `opus-4.6`      |

**Examples:**

```bash
# Default (Nova 2 Lite with low reasoning)
arch-review --documents-dir ./docs --templates-dir ./cdk.out --diagrams-dir ./diagrams

# Claude Opus 4.6 with medium reasoning
arch-review --model opus-4.6 --reasoning-level medium \
    --documents-dir ./docs --templates-dir ./cdk.out --diagrams-dir ./diagrams

# Compare with reasoning off
arch-review --model opus-4.6 --reasoning-level off \
    --documents-dir ./docs --templates-dir ./cdk.out --diagrams-dir ./diagrams
```

**Reasoning levels:**

- `off` -- disable extended thinking entirely
- `low` -- minimal reasoning (default, fastest)
- `medium` -- balanced reasoning
- `high` -- maximum reasoning (slowest, best quality)

### Model Quotas & Cost

AWS Bedrock enforces **daily token quotas** per model at the account level. These quotas are shared across all users and workloads on the same AWS account.

| Model         | Cross-Region Daily Quota | Relative Cost |
| ------------- | ------------------------ | ------------- |
| `nova-2-lite` | ~432M tokens             | Low           |
| `opus-4.6`    | ~2.6M tokens             | High          |

> **Warning:** Opus 4.6 has a very low default daily token quota (~2.6M tokens for cross-region inference). A single architecture review involves multiple agent calls (requirements, architecture, questions, sparring, final review), each consuming tokens. You may only get **1–2 reviews per day** before hitting the limit.
>
> Additionally, Opus 4.6 uses [adaptive thinking](https://docs.aws.amazon.com/bedrock/latest/userguide/claude-messages-adaptive-thinking.html) with automatic interleaved thinking between tool calls. Thinking tokens are billed as output tokens ([docs](https://docs.aws.amazon.com/bedrock/latest/userguide/claude-messages-extended-thinking.html#claude-messages-extended-thinking-cost)) and most Claude models apply a [5x burndown rate](https://docs.aws.amazon.com/bedrock/latest/userguide/quotas-token-burndown.html) on output tokens (1 output token = 5 tokens from your quota). This significantly amplifies quota consumption.
>
> For Nova 2 Lite, reasoning tokens are also charged even though reasoning content is redacted ([docs](https://docs.aws.amazon.com/nova/latest/nova2-userguide/reasoning-capabilities.html)).
>
> For iterative development and frequent reviews, **`nova-2-lite` (the default) is strongly recommended**. Reserve `opus-4.6` for cases where higher reasoning quality is critical.
>
> These quotas are marked as non-adjustable in AWS Service Quotas. Contact AWS Support to request an increase.

### Environment Variables

All options can be set via environment variables:

| Variable                      | Description                              |
| ----------------------------- | ---------------------------------------- |
| `ARCH_REVIEW_DOCUMENTS_DIR`   | Documents directory                      |
| `ARCH_REVIEW_TEMPLATES_DIR`   | Templates directory                      |
| `ARCH_REVIEW_DIAGRAMS_DIR`    | Diagrams directory                       |
| `ARCH_REVIEW_SOURCE_DIR`      | Source code directory                    |
| `ARCH_REVIEW_OUTPUT_DIR`      | Output directory                         |
| `ARCH_REVIEW_MODEL`           | Model short name (nova-2-lite, opus-4.6) |
| `ARCH_REVIEW_REASONING_LEVEL` | Reasoning effort: off, low, medium, high |
| `AWS_REGION`                  | AWS region                               |
| `CI`                          | Enable CI mode (true/1/yes)              |

### Exit Codes

| Code | Meaning                                          |
| ---- | ------------------------------------------------ |
| 0    | PASS - no significant issues found               |
| 1    | FAIL (or --strict with High impact)              |
| 2    | PASS WITH CONCERNS - gaps found but non-critical |
| 3    | Error during execution                           |

## AWS Credentials

The tool uses the standard AWS credential chain.

### Local Development

Configure credentials using any standard method:

```bash
# Option 1: AWS CLI profile
aws configure

# Option 2: Environment variables
export AWS_ACCESS_KEY_ID=...
export AWS_SECRET_ACCESS_KEY=...
export AWS_REGION=us-east-1

# Option 3: AWS SSO
aws sso login --profile my-profile
export AWS_PROFILE=my-profile
```

### CI/CD Environments

Each platform has its own credential mechanism:

| Platform      | Recommended Method          | Credential Source                |
| ------------- | --------------------------- | -------------------------------- |
| GitHub        | OIDC                        | IAM Identity Provider for GitHub |
| GitLab        | OIDC                        | IAM Identity Provider for GitLab |
| AWS CodeBuild | Service Role                | Attached IAM role (automatic)    |
| Jenkins       | Instance Profile or Secrets | EC2 role or credential plugin    |

### Required IAM Permissions

> **Note**: For production use, scope `Resource` to your specific account/region ARNs.

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "BedrockModelAccess",
      "Effect": "Allow",
      "Action": [
        "bedrock:InvokeModel",
        "bedrock:Converse",
        "bedrock:ListFoundationModels"
      ],
      "Resource": "*"
    },
    {
      "Sid": "AgentCorePolicyAndGateway",
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:CreatePolicyEngine",
        "bedrock-agentcore:ListPolicyEngines",
        "bedrock-agentcore:CreatePolicy",
        "bedrock-agentcore:UpdatePolicy",
        "bedrock-agentcore:GetPolicy",
        "bedrock-agentcore:ListPolicies",
        "bedrock-agentcore:CreateGateway",
        "bedrock-agentcore:GetGateway",
        "bedrock-agentcore:UpdateGateway",
        "bedrock-agentcore:ListGateways"
      ],
      "Resource": "*"
    },
    {
      "Sid": "AgentCoreMemory",
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:CreateMemory",
        "bedrock-agentcore:ListMemories"
      ],
      "Resource": "*"
    },
    {
      "Sid": "CallerIdentity",
      "Effect": "Allow",
      "Action": "sts:GetCallerIdentity",
      "Resource": "*"
    }
  ]
}
```

## CI/CD Integration

Example configurations are in `examples/ci/`.

### GitHub Actions

Copy `examples/ci/github-actions.yml` to `.github/workflows/arch-review.yml`:

- Supports OIDC (recommended) or static credentials
- Comments results on PRs
- Uploads review as artifact

### GitLab CI

Copy `examples/ci/gitlab-ci.yml` to `.gitlab-ci.yml`:

- Supports OIDC or CI/CD variables
- Runs on merge requests
- Optional JSON output job

### AWS CodeBuild

Copy `examples/ci/aws-codebuild.yml` to `buildspec.yml`:

- Uses CodeBuild service role automatically
- No credential configuration needed
- Works with CodePipeline

## Review Phases

1. **Requirements Analysis**: Extracts requirements, constraints, and NFRs from documents
2. **Architecture Analysis**: Analyzes CloudFormation templates and diagrams
3. **Clarifying Questions** (interactive) / **Gap Identification** (CI): Gathers context or identifies unknowns
4. **Sparring** (interactive) / **Risk Analysis** (CI): Challenges decisions or lists risks
5. **Final Review**: Produces structured review with gaps, risks, recommendations

## Input Formats

### Documents

Markdown files with requirements, constraints, NFRs, ADRs. No specific format required.

### Templates

- CloudFormation: `.yaml`, `.yml`, `.json`
- CDK: Point to `cdk.out/` directory

### Diagrams

- PNG, JPEG images
- Export draw.io files to PNG/JPEG first

## Project Structure

```
arch_sparring_agent/
├── agents/
│   ├── requirements_agent.py  # Phase 1: Document analysis
│   ├── architecture_agent.py  # Phase 2: Template/diagram analysis
│   ├── question_agent.py      # Phase 3: Interactive questions
│   ├── sparring_agent.py      # Phase 4: Interactive sparring
│   ├── ci_agents.py           # Phase 3-4: CI/CD non-interactive
│   ├── review_agent.py        # Phase 5: Final review
│   └── remediation_agent.py   # Remediation mode discussions
├── tools/
│   ├── document_parser.py     # Markdown file reader
│   ├── cfn_analyzer.py        # CloudFormation template reader
│   ├── diagram_analyzer.py    # Diagram analysis via Bedrock
│   └── source_analyzer.py     # Lambda/application source code reader
├── orchestrator.py            # Phase orchestration
├── config.py                  # Constants and AWS client setup
├── policy.py                  # Cedar policy management
├── gateway.py                 # Gateway setup and lifecycle
├── memory.py                  # AgentCore memory for sessions
├── exceptions.py              # Custom exception hierarchy
├── context_condenser.py       # Handles large inputs
├── state.py                   # Review state persistence
└── cli.py                     # CLI entry point
examples/ci/
├── github-actions.yml         # GitHub Actions example
├── gitlab-ci.yml              # GitLab CI example
└── aws-codebuild.yml          # AWS CodeBuild example
```

## Development

```bash
uv sync                    # Install dependencies
uv run ruff format .       # Format code
uv run ruff check .        # Lint code
```

## Policy Engine

The tool automatically creates and configures a full policy enforcement stack for security:

1. **Creates a Gateway** ("ArchReviewGateway") or uses an existing one
2. **Creates a Policy Engine** ("ArchReviewPolicyEngine") or uses an existing one
3. **Creates Cedar policies** restricting each agent to specific tools:
   - **RequirementsAnalyst**: Only document reading tools
   - **ArchitectureEvaluator**: Only CFN/diagram reading tools
   - **DefaultDeny**: Blocks unknown agents
4. **Associates the Gateway with the Policy Engine** for enforcement

## Technical Details

- **Default Model**: Nova 2 Lite (1M context, multimodal)
- **Multi-model**: Curated registry with Nova 2 Lite and Claude Opus 4.6 via `--model`
- **Framework**: AWS Strands SDK
- **Region**: eu-central-1 (configurable)
- **Policy Engine**: AgentCore Policy Engine for tool access control

## References

- [Strands SDK](https://strandsagents.com/latest/documentation/docs/)
- [Amazon Bedrock](https://docs.aws.amazon.com/bedrock/latest/userguide/)
- [Amazon Nova 2 Models](https://docs.aws.amazon.com/nova/latest/nova2-userguide/)
