aws-bedrock-invoke 1.0.0__tar.gz

aws_bedrock_invoke-1.0.0/.env.example

@@ -0,0 +1,12 @@
+AWS_REGION=us-east-1
+AWS_ACCESS_KEY_ID=
+AWS_SECRET_ACCESS_KEY=
+
+BEDROCK_RETRY_MAX_ATTEMPTS=4
+BEDROCK_RETRY_BASE_SECONDS=5
+BEDROCK_RETRY_MAX_SECONDS=45
+BEDROCK_RETRY_JITTER=true
+BEDROCK_RETRYABLE_ERROR_CODES=
+
+BEDROCK_PROMPT_CACHE_ENABLED=false
+BEDROCK_PROMPT_CACHE_TTL=5m

aws_bedrock_invoke-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,30 @@
+name: Publish Python package
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          username: __token__
+          password: ${{ secrets.PYPI_API_TOKEN }}

aws_bedrock_invoke-1.0.0/.gitignore

@@ -0,0 +1,4 @@
+.env
+__pycache__/
+*.pyc
+.pytest_cache/

aws_bedrock_invoke-1.0.0/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 1.0.0
+
+- Added a focused Claude 4.x AWS Bedrock invocation library
+- Added manual progressive retry with env-driven configuration
+- Added additive default retryable Bedrock error-code handling
+- Added optional Bedrock prompt-cache helpers
+- Added JSON and text invocation helpers
+- Added optional public client injection for adapters and tests
+- Added unit tests and real Bedrock smoke coverage

aws_bedrock_invoke-1.0.0/PKG-INFO

@@ -0,0 +1,223 @@
+Metadata-Version: 2.4
+Name: aws-bedrock-invoke
+Version: 1.0.0
+Summary: Small Python library for invoking Claude 4.x models on AWS Bedrock with manual retries, prompt caching helpers, and JSON parsing.
+Project-URL: Homepage, https://github.com/not-empty/aws-bedrock-invoke-python
+Project-URL: Issues, https://github.com/not-empty/aws-bedrock-invoke-python/issues
+Author-email: Not Empty Foundation <dev@not-empty.org>
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Requires-Dist: boto3>=1.34.0
+Description-Content-Type: text/markdown
+
+# AWS Bedrock Invoke Python
+
+AWS Bedrock Invoke Python is a small library for invoking Claude 4.x models on
+AWS Bedrock with one consistent request path.
+
+It focuses only on the transport layer:
+
+- boto3 client creation
+- optional client injection
+- Bedrock model ID / inference-profile resolution
+- Bedrock prompt-cache helpers
+- manual retry with env-driven configuration
+- response text extraction
+- fenced JSON cleanup and parsing
+
+It intentionally does not own business rules such as batching strategies,
+workflow orchestration, application result caching, or prompt authoring.
+
+## Installation
+
+```bash
+pip install aws-bedrock-invoke
+```
+
+## Scope
+
+This library is intentionally narrow:
+
+- Claude 4.x on AWS Bedrock only
+- manual retry managed by the library
+- Bedrock prompt-cache support
+- text and JSON invoke helpers
+
+This library intentionally does not include:
+
+- business-specific batching/windowing
+- application result caching
+- Slack notifications or persistence
+- prompt engineering or workflow orchestration
+
+## Quick Start
+
+### `invoke_json()`
+
+```python
+from aws_bedrock_invoke import BedrockInvoker, json_text_block
+
+invoker = BedrockInvoker.from_env()
+
+result = invoker.invoke_json(
+    model="us.anthropic.claude-sonnet-4-5-20250929-v1:0",
+    profile_arn_fmt="arn:aws:bedrock:{region}:354173731728:inference-profile/{model}",
+    system_prompt="Reply with strict JSON.",
+    user_content=[
+        json_text_block({"question": "hello"}),
+    ],
+)
+
+print(result.parsed_json)
+print(result.response_text)
+```
+
+### `invoke_text()`
+
+```python
+from aws_bedrock_invoke import BedrockInvoker, text_block
+
+invoker = BedrockInvoker.from_env()
+
+result = invoker.invoke_text(
+    model="us.anthropic.claude-sonnet-4-5-20250929-v1:0",
+    profile_arn_fmt="arn:aws:bedrock:{region}:354173731728:inference-profile/{model}",
+    system_prompt="Answer briefly.",
+    user_content=[
+        text_block("What is a lien waiver?"),
+    ],
+)
+
+print(result.response_text)
+```
+
+## Client Injection
+
+Client injection is optional.
+
+If you do not provide a client, `BedrockInvoker` builds one from
+`BedrockClientConfig`.
+
+If you already have a prepared boto Bedrock client, you can inject it directly.
+This is especially useful for adapters and tests.
+
+```python
+import boto3
+
+from aws_bedrock_invoke import BedrockClientConfig, BedrockInvoker, text_block
+
+client = boto3.client(
+    "bedrock-runtime",
+    region_name="us-east-1",
+    aws_access_key_id="...",
+    aws_secret_access_key="...",
+)
+
+invoker = BedrockInvoker(
+    client_config=BedrockClientConfig(
+        region="us-east-1",
+        aws_access_key_id="...",
+        aws_secret_access_key="...",
+    ),
+    client=client,
+)
+
+result = invoker.invoke_text(
+    model="arn:aws:bedrock:us-east-1:123456789012:inference-profile/example",
+    system_prompt="Answer briefly.",
+    user_content=[text_block("hello")],
+)
+```
+
+## Environment Variables
+
+### AWS / Bedrock
+
+- `AWS_REGION`
+- `AWS_ACCESS_KEY_ID`
+- `AWS_SECRET_ACCESS_KEY`
+
+### Retry
+
+- `BEDROCK_RETRY_MAX_ATTEMPTS`
+- `BEDROCK_RETRY_BASE_SECONDS`
+- `BEDROCK_RETRY_MAX_SECONDS`
+- `BEDROCK_RETRY_JITTER`
+- `BEDROCK_RETRYABLE_ERROR_CODES`
+
+The Bedrock SDK retry behavior is effectively disabled in the client, and the
+library uses its own manual progressive retry loop instead.
+
+Default retryable error codes:
+
+- `ServiceUnavailableException`
+- `InternalServerException`
+
+`BEDROCK_RETRYABLE_ERROR_CODES` is additive. If you set it, the provided codes
+are added on top of those defaults rather than replacing them.
+
+Default retry behavior:
+
+- `BEDROCK_RETRY_MAX_ATTEMPTS=4`
+- `BEDROCK_RETRY_BASE_SECONDS=5`
+- `BEDROCK_RETRY_MAX_SECONDS=45`
+- `BEDROCK_RETRY_JITTER=true`
+
+`on_retry` receives a typed `RetryEvent` with:
+
+- `attempt`
+- `max_attempts`
+- `error_code`
+- `error`
+- `sleep_seconds`
+- `model_id`
+- `elapsed_seconds`
+
+### Prompt Cache
+
+- `BEDROCK_PROMPT_CACHE_ENABLED`
+- `BEDROCK_PROMPT_CACHE_TTL`
+
+## Public API
+
+- `BedrockInvoker`
+- `BedrockClientConfig`
+- `RetryPolicy`
+- `BedrockPromptCacheConfig`
+- `InvokeResult`
+- `RetryEvent`
+- `json_text_block`
+- `text_block`
+- `resolve_model_id`
+
+## Model Resolution
+
+If `model` is a full ARN, the library uses it directly.
+
+If `model` is a shorthand like `us.anthropic...`, you must provide
+`profile_arn_fmt` on the invoke call.
+
+## Testing
+
+Run the test suite locally with:
+
+```bash
+PYTHONPATH=src python3 -m unittest discover -s tests -v
+```
+
+## Examples
+
+Runnable examples live in [examples](/home/disarli/Projects/aws-bedrock-invoke-python/examples):
+
+```bash
+PYTHONPATH=src python3 examples/invoke_json_example.py
+PYTHONPATH=src python3 examples/invoke_text_example.py
+```
+
+## Consumer Integration
+
+This repo includes library-level tests and Bedrock smoke examples.
+
+Consumer repositories should still add their own integration smoke that uses
+their real prompt builders and payload-shaping logic through this library.

aws_bedrock_invoke-1.0.0/README.md

@@ -0,0 +1,210 @@
+# AWS Bedrock Invoke Python
+
+AWS Bedrock Invoke Python is a small library for invoking Claude 4.x models on
+AWS Bedrock with one consistent request path.
+
+It focuses only on the transport layer:
+
+- boto3 client creation
+- optional client injection
+- Bedrock model ID / inference-profile resolution
+- Bedrock prompt-cache helpers
+- manual retry with env-driven configuration
+- response text extraction
+- fenced JSON cleanup and parsing
+
+It intentionally does not own business rules such as batching strategies,
+workflow orchestration, application result caching, or prompt authoring.
+
+## Installation
+
+```bash
+pip install aws-bedrock-invoke
+```
+
+## Scope
+
+This library is intentionally narrow:
+
+- Claude 4.x on AWS Bedrock only
+- manual retry managed by the library
+- Bedrock prompt-cache support
+- text and JSON invoke helpers
+
+This library intentionally does not include:
+
+- business-specific batching/windowing
+- application result caching
+- Slack notifications or persistence
+- prompt engineering or workflow orchestration
+
+## Quick Start
+
+### `invoke_json()`
+
+```python
+from aws_bedrock_invoke import BedrockInvoker, json_text_block
+
+invoker = BedrockInvoker.from_env()
+
+result = invoker.invoke_json(
+    model="us.anthropic.claude-sonnet-4-5-20250929-v1:0",
+    profile_arn_fmt="arn:aws:bedrock:{region}:354173731728:inference-profile/{model}",
+    system_prompt="Reply with strict JSON.",
+    user_content=[
+        json_text_block({"question": "hello"}),
+    ],
+)
+
+print(result.parsed_json)
+print(result.response_text)
+```
+
+### `invoke_text()`
+
+```python
+from aws_bedrock_invoke import BedrockInvoker, text_block
+
+invoker = BedrockInvoker.from_env()
+
+result = invoker.invoke_text(
+    model="us.anthropic.claude-sonnet-4-5-20250929-v1:0",
+    profile_arn_fmt="arn:aws:bedrock:{region}:354173731728:inference-profile/{model}",
+    system_prompt="Answer briefly.",
+    user_content=[
+        text_block("What is a lien waiver?"),
+    ],
+)
+
+print(result.response_text)
+```
+
+## Client Injection
+
+Client injection is optional.
+
+If you do not provide a client, `BedrockInvoker` builds one from
+`BedrockClientConfig`.
+
+If you already have a prepared boto Bedrock client, you can inject it directly.
+This is especially useful for adapters and tests.
+
+```python
+import boto3
+
+from aws_bedrock_invoke import BedrockClientConfig, BedrockInvoker, text_block
+
+client = boto3.client(
+    "bedrock-runtime",
+    region_name="us-east-1",
+    aws_access_key_id="...",
+    aws_secret_access_key="...",
+)
+
+invoker = BedrockInvoker(
+    client_config=BedrockClientConfig(
+        region="us-east-1",
+        aws_access_key_id="...",
+        aws_secret_access_key="...",
+    ),
+    client=client,
+)
+
+result = invoker.invoke_text(
+    model="arn:aws:bedrock:us-east-1:123456789012:inference-profile/example",
+    system_prompt="Answer briefly.",
+    user_content=[text_block("hello")],
+)
+```
+
+## Environment Variables
+
+### AWS / Bedrock
+
+- `AWS_REGION`
+- `AWS_ACCESS_KEY_ID`
+- `AWS_SECRET_ACCESS_KEY`
+
+### Retry
+
+- `BEDROCK_RETRY_MAX_ATTEMPTS`
+- `BEDROCK_RETRY_BASE_SECONDS`
+- `BEDROCK_RETRY_MAX_SECONDS`
+- `BEDROCK_RETRY_JITTER`
+- `BEDROCK_RETRYABLE_ERROR_CODES`
+
+The Bedrock SDK retry behavior is effectively disabled in the client, and the
+library uses its own manual progressive retry loop instead.
+
+Default retryable error codes:
+
+- `ServiceUnavailableException`
+- `InternalServerException`
+
+`BEDROCK_RETRYABLE_ERROR_CODES` is additive. If you set it, the provided codes
+are added on top of those defaults rather than replacing them.
+
+Default retry behavior:
+
+- `BEDROCK_RETRY_MAX_ATTEMPTS=4`
+- `BEDROCK_RETRY_BASE_SECONDS=5`
+- `BEDROCK_RETRY_MAX_SECONDS=45`
+- `BEDROCK_RETRY_JITTER=true`
+
+`on_retry` receives a typed `RetryEvent` with:
+
+- `attempt`
+- `max_attempts`
+- `error_code`
+- `error`
+- `sleep_seconds`
+- `model_id`
+- `elapsed_seconds`
+
+### Prompt Cache
+
+- `BEDROCK_PROMPT_CACHE_ENABLED`
+- `BEDROCK_PROMPT_CACHE_TTL`
+
+## Public API
+
+- `BedrockInvoker`
+- `BedrockClientConfig`
+- `RetryPolicy`
+- `BedrockPromptCacheConfig`
+- `InvokeResult`
+- `RetryEvent`
+- `json_text_block`
+- `text_block`
+- `resolve_model_id`
+
+## Model Resolution
+
+If `model` is a full ARN, the library uses it directly.
+
+If `model` is a shorthand like `us.anthropic...`, you must provide
+`profile_arn_fmt` on the invoke call.
+
+## Testing
+
+Run the test suite locally with:
+
+```bash
+PYTHONPATH=src python3 -m unittest discover -s tests -v
+```
+
+## Examples
+
+Runnable examples live in [examples](/home/disarli/Projects/aws-bedrock-invoke-python/examples):
+
+```bash
+PYTHONPATH=src python3 examples/invoke_json_example.py
+PYTHONPATH=src python3 examples/invoke_text_example.py
+```
+
+## Consumer Integration
+
+This repo includes library-level tests and Bedrock smoke examples.
+
+Consumer repositories should still add their own integration smoke that uses
+their real prompt builders and payload-shaping logic through this library.

aws_bedrock_invoke-1.0.0/docker-compose.yml

@@ -0,0 +1,11 @@
+services:
+  app:
+    image: python:3.12-slim
+    working_dir: /workspace
+    command: tail -f /dev/null
+    tty: true
+    stdin_open: true
+    env_file:
+      - .env
+    volumes:
+      - ./:/workspace

aws_bedrock_invoke-1.0.0/examples/invoke_json_example.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from aws_bedrock_invoke import BedrockInvoker, json_text_block
+
+
+def main() -> None:
+    invoker = BedrockInvoker.from_env()
+
+    result = invoker.invoke_json(
+        model="us.anthropic.claude-sonnet-4-5-20250929-v1:0",
+        profile_arn_fmt="arn:aws:bedrock:{region}:354173731728:inference-profile/{model}",
+        system_prompt="Reply with strict JSON.",
+        user_content=[
+            json_text_block({"question": "hello"}),
+        ],
+    )
+
+    print("parsed_json:")
+    print(result.parsed_json)
+    print()
+    print("response_text:")
+    print(result.response_text)
+
+
+if __name__ == "__main__":
+    main()

aws_bedrock_invoke-1.0.0/examples/invoke_text_example.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from aws_bedrock_invoke import BedrockInvoker
+
+
+def main() -> None:
+    invoker = BedrockInvoker.from_env()
+
+    result = invoker.invoke_text(
+        model="us.anthropic.claude-sonnet-4-5-20250929-v1:0",
+        profile_arn_fmt="arn:aws:bedrock:{region}:354173731728:inference-profile/{model}",
+        system_prompt="Answer briefly.",
+        user_content=[
+            {"type": "text", "text": "What is a lien waiver?"},
+        ],
+    )
+
+    print(result.response_text)
+
+
+if __name__ == "__main__":
+    main()

aws_bedrock_invoke-1.0.0/pyproject.toml

@@ -0,0 +1,27 @@
+[project]
+name = "aws-bedrock-invoke"
+version = "1.0.0"
+authors = [
+  { name="Not Empty Foundation", email="dev@not-empty.org" },
+]
+description = "Small Python library for invoking Claude 4.x models on AWS Bedrock with manual retries, prompt caching helpers, and JSON parsing."
+readme = "README.md"
+requires-python = ">=3.10"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "boto3>=1.34.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/not-empty/aws-bedrock-invoke-python"
+Issues = "https://github.com/not-empty/aws-bedrock-invoke-python/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/aws_bedrock_invoke"]

aws_bedrock_invoke-1.0.0/src/aws_bedrock_invoke/__init__.py

@@ -0,0 +1,17 @@
+from .config import BedrockClientConfig, BedrockPromptCacheConfig
+from .content import json_text_block, text_block
+from .invoker import BedrockInvoker, InvokeResult, RetryEvent
+from .retry import RetryPolicy
+from .utils import resolve_model_id
+
+__all__ = [
+    "BedrockClientConfig",
+    "BedrockInvoker",
+    "BedrockPromptCacheConfig",
+    "InvokeResult",
+    "RetryEvent",
+    "RetryPolicy",
+    "json_text_block",
+    "text_block",
+    "resolve_model_id",
+]

aws_bedrock_invoke-1.0.0/src/aws_bedrock_invoke/config.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+
+def _env_truthy(name: str, default: bool = False) -> bool:
+    raw = str(os.getenv(name, "") or "").strip().lower()
+    if not raw:
+        return default
+    return raw in {"1", "true", "yes", "on"}
+
+
+@dataclass(slots=True)
+class BedrockPromptCacheConfig:
+    enabled: bool = False
+    ttl: str | None = None
+
+    @classmethod
+    def from_env(cls) -> "BedrockPromptCacheConfig":
+        return cls(
+            enabled=_env_truthy("BEDROCK_PROMPT_CACHE_ENABLED", default=False),
+            ttl=str(os.getenv("BEDROCK_PROMPT_CACHE_TTL", "") or "").strip() or None,
+        )
+
+
+@dataclass(slots=True)
+class BedrockClientConfig:
+    region: str
+    aws_access_key_id: str | None = None
+    aws_secret_access_key: str | None = None
+    connect_timeout: int = 10
+    read_timeout: int = 300
+    max_pool_connections: int | None = None
+
+    @classmethod
+    def from_env(cls) -> "BedrockClientConfig":
+        region = str(os.getenv("AWS_REGION", "us-east-1") or "").strip()
+        return cls(
+            region=region,
+            aws_access_key_id=str(os.getenv("AWS_ACCESS_KEY_ID", "") or "").strip() or None,
+            aws_secret_access_key=str(os.getenv("AWS_SECRET_ACCESS_KEY", "") or "").strip() or None,
+        )

aws_bedrock_invoke-1.0.0/src/aws_bedrock_invoke/content.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from .config import BedrockPromptCacheConfig
+
+
+def prompt_cache_to_cache_control(
+    config: BedrockPromptCacheConfig | None,
+) -> dict[str, Any] | None:
+    if config is None or not config.enabled:
+        return None
+    cache_control: dict[str, Any] = {"type": "ephemeral"}
+    if config.ttl:
+        cache_control["ttl"] = config.ttl
+    return cache_control
+
+
+def json_text_block(
+    payload: dict[str, Any],
+    *,
+    bedrock_prompt_cache: BedrockPromptCacheConfig | None = None,
+) -> dict[str, Any]:
+    block: dict[str, Any] = {
+        "type": "text",
+        "text": json.dumps(payload, ensure_ascii=False),
+    }
+    cache_control = prompt_cache_to_cache_control(bedrock_prompt_cache)
+    if cache_control is not None:
+        block["cache_control"] = cache_control
+    return block
+
+
+def text_block(
+    text: str,
+    *,
+    bedrock_prompt_cache: BedrockPromptCacheConfig | None = None,
+) -> dict[str, Any]:
+    block: dict[str, Any] = {
+        "type": "text",
+        "text": text,
+    }
+    cache_control = prompt_cache_to_cache_control(bedrock_prompt_cache)
+    if cache_control is not None:
+        block["cache_control"] = cache_control
+    return block

aws_bedrock_invoke-1.0.0/src/aws_bedrock_invoke/exceptions.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+
+class BedrockInvokeError(Exception):
+    pass
+
+
+class BedrockResponseParseError(BedrockInvokeError):
+    pass