Building Valo: AWS Session Management — When to Adapt vs. Copy Production Patterns

The best way to learn from production code isn't always to copy it.

Today we implemented AWS session management for Valo, studying Anthropic's Sentinel production patterns and making a key architectural decision: library functions over CLI scripts.

The Problem: AWS Credential Management Hell

Every AWS service interaction requires credentials. You can pass them everywhere (verbose, error-prone), use environment variables only (inflexible), or use the AWS credential chain (works great but lacks abstraction).

We needed Option 3 with better abstractions.

Studying Sentinel's Approach

Sentinel's design:

• CLI script for session creation
• Handles role assumption
• Shell-based workflow

Why it works for Sentinel:

• CLI-first architecture
• Role assumption is common
• Shell integration needed

Why it doesn't fit Valo:

• Library-first architecture
• Python package imports, not CLI
• Need simple function calls
• Role assumption is future work (YAGNI for MVP)

Our Solution: Library Functions

We extracted the core concepts and built cleaner library functions:

Core API: Two Functions

def create_session(
    region: str | None = None,
    aws_access_key_id: str | None = None,
    aws_secret_access_key: str | None = None,
    aws_session_token: str | None = None,
) -> boto3.Session:
    """Create a boto3 session with optional credentials.

    Falls back to AWS credential chain if credentials not provided.
    """

def get_aws_client(
    service_name: str,
    region: str | None = None,
    session: boto3.Session | None = None,
    **kwargs: Any,
) -> Any:
    """Get an AWS service client with proper configuration.

    Can use existing session or create new one with credentials.
    """

Testing Without Real AWS: Enter Moto

The moto library provides AWS service mocks:

Benefits:

• No real AWS credentials needed
• Tests run in CI/CD without configuration
• Fast (no network calls)
• Repeatable results

Type Safety with boto3-stubs

boto3 doesn't ship with type stubs. We added boto3-stubs[essential] for type hints.

Result: Type-safe code with IDE autocomplete and mypy strict mode compliance.

Pattern Adaptation: Learn, Don't Copy

What we learned from Sentinel:

• AWS credential management is complex
• Role assumption patterns exist
• Error handling is critical
• Region configuration needs flexibility

What we changed:

• CLI script → Library functions
• Shell integration → Python API
• Command-line args → Function parameters
• Role assumption (deferred to future work)

Result: Code that solves our specific problem better than copying would have.

Quality Metrics

• 83 tests passing (16 new AWS session tests)
• 94% overall coverage (AWS session: 80%)
• Zero mypy errors (strict mode)
• Zero ruff errors

Adapted. Not copied. Better.