macomb-bedrock 0.1.0__tar.gz

macomb_bedrock-0.1.0/PKG-INFO

@@ -0,0 +1,54 @@
+Metadata-Version: 2.5
+Name: macomb-bedrock
+Version: 0.1.0
+Summary: Amazon Bedrock helpers for ITIA 1510 lab activities
+Requires-Python: >=3.12
+Requires-Dist: boto3
+Description-Content-Type: text/markdown
+
+# macomb-bedrock
+
+Amazon Bedrock helpers for the ITIA 1510 lab activities at Macomb Community College. The package sends prompts to Amazon Nova Micro (`amazon.nova-micro-v1:0`, us-east-1) through the Amazon Bedrock Converse API.
+
+## Install
+
+```
+python3.13 -m pip install macomb-bedrock==0.1.0
+```
+
+## Use
+
+```python
+from macomb_bedrock import ask, ask_history
+
+print(ask("What makes a password strong?"))
+
+conversation = [
+    "Is Summer2024! a strong password?",
+    "It is weak: it follows a season and year pattern.",
+    "Why does that pattern matter?",
+]
+print(ask_history(conversation))
+```
+
+| Name | What it does |
+|---|---|
+| `ask(prompt, system, client)` | Sends one prompt and returns the reply text |
+| `ask_history(messages, system, client)` | Sends a conversation (user, assistant, user, ...) and returns the reply text |
+| `call_cost(input_tokens, output_tokens)` | Returns the cost of one call in US dollars |
+| `make_client()` | Returns a boto3 `bedrock-runtime` client for us-east-1 |
+| `FakeClient(replies)` | A stand-in client for tests; returns the given replies in order and records each request |
+| `fake_response(text, ...)` | A dictionary shaped like a Converse response |
+| `BedrockError` | Raised with a plain explanation when a call fails or the reply is blocked by the content filter |
+
+The lab server's IAM role grants the permission to call the model. The package holds no keys or passwords.
+
+## Build and publish
+
+```
+py -m build
+py -m twine upload --repository testpypi dist/*
+py -m twine upload dist/*
+```
+
+A version number can be uploaded to PyPI only once. Change `version` in `pyproject.toml` and `__version__` in `src/macomb_bedrock/__init__.py` before each release.

macomb_bedrock-0.1.0/README.md

@@ -0,0 +1,46 @@
+# macomb-bedrock
+
+Amazon Bedrock helpers for the ITIA 1510 lab activities at Macomb Community College. The package sends prompts to Amazon Nova Micro (`amazon.nova-micro-v1:0`, us-east-1) through the Amazon Bedrock Converse API.
+
+## Install
+
+```
+python3.13 -m pip install macomb-bedrock==0.1.0
+```
+
+## Use
+
+```python
+from macomb_bedrock import ask, ask_history
+
+print(ask("What makes a password strong?"))
+
+conversation = [
+    "Is Summer2024! a strong password?",
+    "It is weak: it follows a season and year pattern.",
+    "Why does that pattern matter?",
+]
+print(ask_history(conversation))
+```
+
+| Name | What it does |
+|---|---|
+| `ask(prompt, system, client)` | Sends one prompt and returns the reply text |
+| `ask_history(messages, system, client)` | Sends a conversation (user, assistant, user, ...) and returns the reply text |
+| `call_cost(input_tokens, output_tokens)` | Returns the cost of one call in US dollars |
+| `make_client()` | Returns a boto3 `bedrock-runtime` client for us-east-1 |
+| `FakeClient(replies)` | A stand-in client for tests; returns the given replies in order and records each request |
+| `fake_response(text, ...)` | A dictionary shaped like a Converse response |
+| `BedrockError` | Raised with a plain explanation when a call fails or the reply is blocked by the content filter |
+
+The lab server's IAM role grants the permission to call the model. The package holds no keys or passwords.
+
+## Build and publish
+
+```
+py -m build
+py -m twine upload --repository testpypi dist/*
+py -m twine upload dist/*
+```
+
+A version number can be uploaded to PyPI only once. Change `version` in `pyproject.toml` and `__version__` in `src/macomb_bedrock/__init__.py` before each release.

macomb_bedrock-0.1.0/pyproject.toml

@@ -0,0 +1,19 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "macomb-bedrock"
+version = "0.1.0"
+description = "Amazon Bedrock helpers for ITIA 1510 lab activities"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = ["boto3"]
+
+# Only these go into the source archive. Everything else in the folder
+# (examples with their solutions, any personal files) stays off PyPI.
+[tool.hatch.build.targets.sdist]
+only-include = ["src", "tests", "README.md", "pyproject.toml"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/macomb_bedrock"]

macomb_bedrock-0.1.0/src/macomb_bedrock/__init__.py

@@ -0,0 +1,156 @@
+"""
+macomb_bedrock -- Amazon Bedrock helpers for ITIA 1510 lab activities.
+
+Every function here sends a request to Amazon Nova Micro through the Amazon
+Bedrock Converse API, or pretends to. The Converse call itself is in ask_history(),
+so stepping into ask() with the debugger shows the whole request and response.
+
+   ask(prompt)              send one prompt, return the reply text
+   ask_history(messages)    send a whole conversation, return the reply text
+   call_cost(tokens...)     the cost of one call in US dollars
+   FakeClient               a stand-in for the real client, used by tests
+
+The lab server already has permission to call Nova Micro. There is no key or
+password in this package, and there never should be.
+"""
+
+from typing import Any
+
+import boto3
+from botocore.exceptions import ClientError
+
+__version__ = "0.1.0"
+
+MODEL_ID = "amazon.nova-micro-v1:0"
+REGION = "us-east-1"
+MAX_TOKENS = 300
+
+SYSTEM_PROMPT = (
+    "You are a cybersecurity tutor helping an IT team. "
+    "Answer in one short paragraph."
+)
+
+# US dollars per token: $0.035 per million input tokens, $0.14 per million
+# output tokens.
+INPUT_PRICE = 0.035 / 1_000_000
+OUTPUT_PRICE = 0.14 / 1_000_000
+
+FILTERED_MESSAGE = (
+    "The reply was blocked by the model's content filter. "
+    "Change the wording of the prompt or the system prompt and try again."
+)
+
+ERROR_MESSAGES = {
+    "ThrottlingException": (
+        "Too many requests in a short time. Wait a few seconds and try again."
+    ),
+    "AccessDeniedException": (
+        "This lab is not allowed to call the model. Either the lab's $1 "
+        "spending limit was reached, or the lab has no Bedrock permission."
+    ),
+    "ValidationException": (
+        "Bedrock refused the request because its shape is wrong. The "
+        "details are below."
+    ),
+}
+
+
+class BedrockError(Exception):
+    """A failed model call, explained in plain words."""
+
+
+def make_client() -> Any:
+    """Return a client that sends requests to Amazon Bedrock in us-east-1."""
+    return boto3.client("bedrock-runtime", region_name=REGION)
+
+
+def ask(prompt: str, system: str = SYSTEM_PROMPT, client: Any = None) -> str:
+    """Send one prompt to the model and return the text of its reply."""
+    return ask_history([prompt], system, client)
+
+
+def ask_history(messages: list[str], system: str = SYSTEM_PROMPT,
+                client: Any = None) -> str:
+    """Send a conversation to the model and return the text of its reply.
+
+    messages holds the conversation so far as plain strings. The first is
+    from the user, the next is the model's reply, and so on, so the list
+    must have an odd length: it ends with the user's newest message.
+    """
+    if len(messages) % 2 == 0:
+        raise ValueError(
+            "messages must start and end with a user message, so it needs "
+            "an odd number of items. It has " + str(len(messages)) + "."
+        )
+
+    history = []
+    for i in range(len(messages)):
+        if i % 2 == 0:
+            role = "user"
+        else:
+            role = "assistant"
+        history.append({"role": role, "content": [{"text": messages[i]}]})
+
+    if client is None:
+        client = make_client()
+
+    try:
+        response = client.converse(
+            modelId=MODEL_ID,
+            messages=history,
+            system=[{"text": system}],
+            inferenceConfig={"maxTokens": MAX_TOKENS, "temperature": 0},
+        )
+    except ClientError as error:
+        code = error.response["Error"]["Code"]
+        explanation = ERROR_MESSAGES.get(code, "The model call failed.")
+        raise BedrockError(explanation + "\n" + str(error)) from error
+
+    if response["stopReason"] == "content_filtered":
+        raise BedrockError(FILTERED_MESSAGE)
+
+    return response["output"]["message"]["content"][0]["text"]
+
+
+def call_cost(input_tokens: int, output_tokens: int) -> float:
+    """Return the cost of one call in US dollars."""
+    return input_tokens * INPUT_PRICE + output_tokens * OUTPUT_PRICE
+
+
+def fake_response(text: str, stop_reason: str = "end_turn",
+                  input_tokens: int = 10, output_tokens: int = 5) -> dict[str, Any]:
+    """Return a dictionary shaped like a real Converse response."""
+    return {
+        "output": {
+            "message": {"role": "assistant", "content": [{"text": text}]},
+        },
+        "stopReason": stop_reason,
+        "usage": {
+            "inputTokens": input_tokens,
+            "outputTokens": output_tokens,
+            "totalTokens": input_tokens + output_tokens,
+        },
+    }
+
+
+class FakeClient:
+    """A stand-in for the real client, so tests never call the model.
+
+    It returns the replies it was given, one per call, in order, and keeps
+    every request it received in requests, so a test can check what was sent.
+    """
+
+    def __init__(self, replies: list[str]) -> None:
+        self.replies = replies
+        self.requests: list[dict[str, Any]] = []
+
+    def converse(self, **request: Any) -> dict[str, Any]:
+        """Record the request and return the next reply."""
+        self.requests.append(request)
+        if len(self.requests) > len(self.replies):
+            raise AssertionError(
+                "FakeClient was called " + str(len(self.requests))
+                + " times but was given only " + str(len(self.replies))
+                + " replies."
+            )
+        return fake_response(self.replies[len(self.requests) - 1])

macomb_bedrock-0.1.0/tests/test_macomb_bedrock.py

@@ -0,0 +1,78 @@
+"""Tests for macomb_bedrock. They use FakeClient, so they never call the model."""
+
+import pytest
+from botocore.exceptions import ClientError
+
+import macomb_bedrock
+from macomb_bedrock import (
+    BedrockError,
+    FakeClient,
+    ask,
+    ask_history,
+    call_cost,
+    fake_response,
+)
+
+
+def test_ask_returns_reply_text() -> None:
+    client = FakeClient(["Use a long passphrase."])
+    assert ask("What makes a password strong?", client=client) == "Use a long passphrase."
+
+
+def test_ask_sends_one_user_message() -> None:
+    client = FakeClient(["ok"])
+    ask("Hello", client=client)
+    request = client.requests[0]
+    assert request["modelId"] == "amazon.nova-micro-v1:0"
+    assert request["messages"] == [{"role": "user", "content": [{"text": "Hello"}]}]
+    assert request["system"] == [{"text": macomb_bedrock.SYSTEM_PROMPT}]
+    assert request["inferenceConfig"]["temperature"] == 0
+
+
+def test_ask_uses_given_system_prompt() -> None:
+    client = FakeClient(["ok"])
+    ask("Hello", system="Answer in one word.", client=client)
+    assert client.requests[0]["system"] == [{"text": "Answer in one word."}]
+
+
+def test_ask_history_alternates_roles() -> None:
+    client = FakeClient(["third reply"])
+    ask_history(["first", "second", "third"], client=client)
+    roles = [message["role"] for message in client.requests[0]["messages"]]
+    assert roles == ["user", "assistant", "user"]
+
+
+def test_ask_history_rejects_even_length() -> None:
+    with pytest.raises(ValueError):
+        ask_history(["first", "second"], client=FakeClient(["ok"]))
+
+
+def test_content_filter_raises_bedrock_error() -> None:
+    class FilteredClient:
+        def converse(self, **request: object) -> dict:
+            return fake_response("blocked", stop_reason="content_filtered")
+
+    with pytest.raises(BedrockError, match="content filter"):
+        ask("Hello", client=FilteredClient())
+
+
+def test_access_denied_explains_spending_limit() -> None:
+    class DeniedClient:
+        def converse(self, **request: object) -> dict:
+            error = {"Error": {"Code": "AccessDeniedException", "Message": "denied"}}
+            raise ClientError(error, "Converse")
+
+    with pytest.raises(BedrockError, match="spending limit"):
+        ask("Hello", client=DeniedClient())
+
+
+def test_fake_client_runs_out_of_replies() -> None:
+    client = FakeClient(["only one"])
+    ask("first", client=client)
+    with pytest.raises(AssertionError):
+        ask("second", client=client)
+
+
+def test_call_cost() -> None:
+    assert call_cost(1_000_000, 1_000_000) == pytest.approx(0.175)
+    assert call_cost(473, 69) == pytest.approx(0.000026215)