SAP tools for agents

"""Unit 9: SAP tools for agents.

Three tools over SAP's Sales Order API (API_SALES_ORDER_SRV), wrapped in the controls an agent
needs: input validation, the user's scope, limits, an audit log, and an idempotent draft tool
that changes nothing in SAP.

    python unit09/sap_tools.py tools --user ana        what a model would be offered for Ana
    python unit09/sap_tools.py demo --sample           a scripted agent session on made-up data
    python unit09/sap_tools.py demo                    the same against SAP's sandbox (SAP_API_KEY)
    python unit09/sap_tools.py call sales_order_get sales_order=4711 --user ana --sample
    python unit09/sap_tools.py audit                   summarize the audit log

Nothing here sends a change to SAP. Every request to SAP is a GET.
"""
import argparse
import hashlib
import json
import os
import re
import sys
import time
import uuid
from datetime import datetime, timezone
from decimal import Decimal
from pathlib import Path

HERE = Path(__file__).resolve().parent
AUDIT_LOG = HERE / "tool_audit.jsonl"
DRAFTS = HERE / "release_drafts.json"

SERVICE = "/sap/opu/odata/sap/API_SALES_ORDER_SRV"
SANDBOX = "https://sandbox.api.sap.com/s4hanacloud" + SERVICE

HEADER_FIELDS = ["SalesOrder", "SalesOrganization", "SoldToParty", "CreationDate", "TotalNetAmount",
                 "TransactionCurrency", "DeliveryBlockReason", "HeaderBillingBlockReason",
                 "TotalCreditCheckStatus"]
ITEM_FIELDS = ["SalesOrderItem", "Material", "SalesOrderItemText", "RequestedQuantity",
               "RequestedQuantityUnit", "NetAmount", "ItemBillingBlockReason"]

MAX_TOOL_CALLS = 12      # per session: an agent that loops stops here
MAX_SAP_REQUESTS = 30    # per session: protects SAP from a runaway agent
SCAN_ROWS = 50           # the most orders one search reads from SAP

# Made-up people the agent acts for. In a real system this comes from the signed-in user's
# token and SAP's own authorizations, never from the model.
USERS = {
    "ana": {"display": "Ana, order clerk, sales org 1010", "sales_orgs": ["1010"], "roles": ["ORDER_CLERK"]},
    "ben": {"display": "Ben, order clerk, sales org 1710", "sales_orgs": ["1710"], "roles": ["ORDER_CLERK"]},
    "kim": {"display": "Kim, auditor, sales org 1010", "sales_orgs": ["1010"], "roles": ["AUDITOR"]},
}


class ToolError(Exception):
    """An expected problem. Its message goes back to the model, so it says what to do next."""


class SAPError(Exception):
    """SAP answered with an error, or could not be reached."""


# ------------------------------------------------------------------ talking to SAP

class LiveSAP:
    """Sends real GET requests to SAP's sandbox with your API key."""

    name = "SAP sandbox (shared API key)"

    def __init__(self, key: str):
        import requests  # imported here so --sample works without the library
        self.requests = requests
        self.session = requests.Session()
        self.session.headers.update({"APIKey": key, "Accept": "application/json"})

    def get(self, path: str, params: dict | None = None) -> dict:
        for attempt in (1, 2):  # GET is safe to repeat; retry once on "busy" answers
            try:
                resp = self.session.get(SANDBOX + path, params=params, timeout=30)
            except self.requests.exceptions.RequestException as err:
                raise SAPError(f"could not reach sandbox.api.sap.com ({type(err).__name__})")
            if resp.status_code in (429, 502, 503, 504) and attempt == 1:
                time.sleep(2)
                continue
            break
        if resp.status_code == 404:
            return {}
        if resp.status_code != 200:
            raise SAPError(f"HTTP {resp.status_code}: {resp.text[:200]}")
        return resp.json().get("d", {})


class SampleSAP:
    """Answers like the Sales Order API would, from made-up data. Understands the few
    query options this script uses: $filter (eq, ne, and), $select, $top, $orderby.
    Dates sort correctly here because every sample date has the same number of digits."""

    name = "made-up sample data"

    def get(self, path: str, params: dict | None = None) -> dict:
        params = params or {}
        one = re.fullmatch(r"/A_SalesOrder\('(\d+)'\)", path)
        child = re.fullmatch(r"/A_SalesOrder\('(\d+)'\)/(to_\w+)", path)
        if one:
            row = next((o for o in SAMPLE_ORDERS if o["SalesOrder"] == one.group(1)), None)
            return select(row, params) if row else {}
        if child and child.group(2) in SAMPLE_CHILDREN:
            rows = SAMPLE_CHILDREN[child.group(2)].get(child.group(1), [])
        elif path == "/A_SalesOrder":
            rows = [o for o in SAMPLE_ORDERS if matches(o, params.get("$filter", ""))]
            field, _, direction = params.get("$orderby", "SalesOrder").partition(" ")
            rows.sort(key=lambda o: o.get(field, ""), reverse=direction == "desc")
        else:
            raise SAPError(f"HTTP 404: no such resource {path}")
        rows = rows[:int(params.get("$top", len(rows)))]
        return {"results": [select(r, params) for r in rows]}


def matches(row: dict, odata_filter: str) -> bool:
    """Evaluate a simple OData filter such as: SalesOrganization eq '1010' and SoldToParty eq '17100001'."""
    for part in filter(None, odata_filter.split(" and ")):
        m = re.fullmatch(r"(\w+) (eq|ne) '([^']*)'", part.strip())
        if not m:
            raise SAPError(f"HTTP 400: sample data can't read the filter {part!r}")
        field, op, value = m.groups()
        if (row.get(field, "") == value) != (op == "eq"):
            return False
    return True


def select(row: dict, params: dict) -> dict:
    keep = params.get("$select")
    return {k: row[k] for k in keep.split(",") if k in row} if keep else dict(row)


def ms(day: str) -> str:
    """Write a date the way OData V2 JSON does: /Date(milliseconds since 1970)/."""
    stamp = datetime.fromisoformat(day).replace(tzinfo=timezone.utc).timestamp()
    return f"/Date({int(stamp * 1000)})/"


def order(no, org, customer, day, amount, delivery="", billing="", credit=""):
    return {"SalesOrder": no, "SalesOrganization": org, "SoldToParty": customer, "CreationDate": ms(day),
            "TotalNetAmount": amount, "TransactionCurrency": "EUR" if org == "1010" else "USD",
            "DeliveryBlockReason": delivery, "HeaderBillingBlockReason": billing,
            "TotalCreditCheckStatus": credit}


SAMPLE_ORDERS = [
    order("4711", "1010", "10100001", "2026-09-28", "18250.00", delivery="01", credit="B"),
    order("4712", "1010", "10100002", "2026-09-29", "940.00", billing="02"),
    order("4715", "1010", "10100001", "2026-09-30", "5100.00"),
    order("4718", "1010", "10100003", "2026-10-01", "7300.00", delivery="01"),
    order("4801", "1710", "17100001", "2026-09-30", "22400.00", delivery="01", credit="B"),
    order("4802", "1710", "17100002", "2026-10-01", "3150.00"),
]
SAMPLE_ITEMS = {
    "4711": [{"SalesOrderItem": "10", "Material": "TG11", "SalesOrderItemText": "Trading good 11",
              "RequestedQuantity": "50", "RequestedQuantityUnit": "PC", "NetAmount": "18250.00",
              "ItemBillingBlockReason": ""}],
    "4718": [{"SalesOrderItem": "10", "Material": "TG12", "SalesOrderItemText": "Trading good 12",
              "RequestedQuantity": "20", "RequestedQuantityUnit": "PC", "NetAmount": "7300.00",
              "ItemBillingBlockReason": ""}],
}
SAMPLE_CHILDREN = {"to_Item": SAMPLE_ITEMS}   # navigation name -> records per sales order


# ------------------------------------------------------------------ helpers for the tools

def odata_date(value: str | None) -> str | None:
    m = re.search(r"/Date\((-?\d+)", value or "")
    if not m:
        return value
    return datetime.fromtimestamp(int(m.group(1)) / 1000, tz=timezone.utc).date().isoformat()


def blocks(row: dict) -> list[str]:
    """Which blocks are set. Codes stay raw: what '01' means is configured in each system."""
    found = []
    if row.get("DeliveryBlockReason"):
        found.append(f"delivery block, reason code {row['DeliveryBlockReason']}")
    if row.get("HeaderBillingBlockReason"):
        found.append(f"billing block, reason code {row['HeaderBillingBlockReason']}")
    if row.get("TotalCreditCheckStatus") == "B":
        found.append("credit check status B")
    return found


def header_summary(row: dict) -> dict:
    return {"sales_order": row["SalesOrder"], "customer": row.get("SoldToParty"),
            "sales_org": row.get("SalesOrganization"), "created_on": odata_date(row.get("CreationDate")),
            "net_amount": str(Decimal(row.get("TotalNetAmount") or "0")),
            "currency": row.get("TransactionCurrency"), "blocks": blocks(row)}


def read_visible_order(ctx, number: str) -> dict:
    """Read one header and check it is in the user's scope. The same answer for 'missing' and
    'not yours', so the agent can't learn that an order exists in another sales org."""
    row = ctx.sap_get(f"/A_SalesOrder('{number}')", {"$select": ",".join(HEADER_FIELDS)})
    if not row or row.get("SalesOrganization") not in ctx.user["sales_orgs"]:
        raise ToolError(f"Sales order {number} does not exist or you may not see it. Check the number "
                        "with the user; to find their blocked orders, use sales_order_list_blocked.")
    return row


# ------------------------------------------------------------------ the tools

TOOLS = {}


def tool(name, kind, description, params, required=(), roles=("ORDER_CLERK", "AUDITOR")):
    """Register a tool with what the model sees (name, description, schema) and what only
    your code sees (kind, roles, the SAP API it calls)."""
    def register(fn):
        TOOLS[name] = {"fn": fn, "kind": kind, "roles": set(roles), "sap_api": "API_SALES_ORDER_SRV",
                       "definition": {"name": name, "description": description, "parameters": {
                           "type": "object", "properties": params, "required": list(required),
                           "additionalProperties": False}}}
        return fn
    return register


@tool("sales_order_list_blocked", "read",
      "List the user's sales orders that have a delivery block, a billing block or credit check "
      "status B, newest first. Returns order number, customer, amount and the blocks in words. "
      "Use it when the user asks which orders are stuck. Read-only; it only sees the user's own "
      "sales organizations and scans at most the 50 newest orders per organization.",
      {"customer": {"type": ["string", "null"], "pattern": r"^\d{1,10}$",
                    "description": "Optional customer number (SoldToParty), digits only, e.g. '10100001'."},
       "limit": {"type": ["integer", "null"], "minimum": 1, "maximum": 20,
                 "description": "How many orders to return, 1 to 20. Default 10."}})
def sales_order_list_blocked(ctx, customer=None, limit=None):
    limit = limit or 10
    found, scanned = [], 0
    for org in ctx.user["sales_orgs"]:        # scope comes from the user, never from the model
        flt = f"SalesOrganization eq '{org}'" + (f" and SoldToParty eq '{customer}'" if customer else "")
        page = ctx.sap_get("/A_SalesOrder", {"$filter": flt, "$select": ",".join(HEADER_FIELDS),
                                             "$orderby": "CreationDate desc", "$top": str(SCAN_ROWS)})
        rows = page.get("results", [])
        scanned += len(rows)
        found += [header_summary(r) for r in rows
                  if r.get("SalesOrganization") in ctx.user["sales_orgs"] and blocks(r)]  # check after
    result = {"orders": found[:limit], "blocked_found": len(found), "orders_scanned": scanned}
    if len(found) > limit:
        result["note"] = f"Showing {limit} of {len(found)}. Raise limit (max 20) or filter by customer."
    if not found:
        result["note"] = "No blocked orders in the scanned orders. This is a valid answer, not an error."
    return result


@tool("sales_order_get", "read",
      "Read one sales order: customer, amount, creation date, the blocks in words, and up to 20 "
      "items with material, quantity and value. Use it after sales_order_list_blocked, or when the "
      "user names an order. Read-only. Order numbers are digits only, without prefixes.",
      {"sales_order": {"type": "string", "pattern": r"^\d{1,10}$",
                       "description": "Sales order number, digits only, e.g. '4711'. Remove prefixes like 'SO-'."}},
      required=("sales_order",))
def sales_order_get(ctx, sales_order):
    row = read_visible_order(ctx, sales_order)
    items = ctx.sap_get(f"/A_SalesOrder('{sales_order}')/to_Item",
                        {"$select": ",".join(ITEM_FIELDS), "$top": "20"}).get("results", [])
    summary = header_summary(row)
    summary["items"] = [{"item": i.get("SalesOrderItem"), "material": i.get("Material"),
                         "text": i.get("SalesOrderItemText"),
                         "quantity": str(Decimal(i.get("RequestedQuantity") or "0")),
                         "unit": i.get("RequestedQuantityUnit"),
                         "net_amount": str(Decimal(i.get("NetAmount") or "0"))} for i in items]
    return summary


@tool("release_request_draft", "draft",
      "Draft a request to release one blocked sales order, for a person to review and approve. "
      "It does NOT change anything in SAP and does not release the order. Calling it again for the "
      "same order returns the existing draft instead of making a second one. Use it only after "
      "reading the order with sales_order_get, and only when the user asks for a release.",
      {"sales_order": {"type": "string", "pattern": r"^\d{1,10}$",
                       "description": "Sales order number, digits only, e.g. '4711'."},
       "justification": {"type": "string", "minLength": 20, "maxLength": 500,
                         "description": "Why the order should be released, in the user's words, 20 to 500 characters."}},
      required=("sales_order", "justification"), roles=("ORDER_CLERK",))
def release_request_draft(ctx, sales_order, justification):
    row = read_visible_order(ctx, sales_order)
    if not blocks(row):
        raise ToolError(f"Sales order {sales_order} has no block, so there is nothing to release. "
                        "Tell the user; don't draft a request.")
    # Idempotency key: the same user asking for the same action on the same order is one request.
    key = hashlib.sha256(f"{ctx.user_id}|release|{sales_order}".encode()).hexdigest()[:16]
    drafts = json.loads(DRAFTS.read_text(encoding="utf-8")) if DRAFTS.exists() else {}
    if key in drafts:
        return {"draft_id": drafts[key]["draft_id"], "status": drafts[key]["status"], "duplicate": True,
                "message": "A draft for this order already exists; no second draft was made. Nothing in SAP changed."}
    draft = {"draft_id": f"D-{len(drafts) + 1:04d}", "status": "awaiting_approval", "sales_order": sales_order,
             "requested_by": ctx.user_id, "justification": " ".join(justification.split()),
             "order_snapshot": header_summary(row), "created_at": now(), "idempotency_key": key}
    drafts[key] = draft
    DRAFTS.write_text(json.dumps(drafts, indent=2), encoding="utf-8")
    return {"draft_id": draft["draft_id"], "status": draft["status"], "duplicate": False,
            "message": "Draft saved for approval. Nothing in SAP changed; a person decides."}


# ------------------------------------------------------------------ the gateway every call goes through

def now() -> str:
    return datetime.now(timezone.utc).isoformat(timespec="seconds")


class Session:
    """One agent session for one user: holds the SAP connection, counters and the audit trail."""

    def __init__(self, api, user_id: str):
        if user_id not in USERS:
            sys.exit(f"Unknown user {user_id!r}. Choose one of: {', '.join(USERS)}")
        self.api, self.user_id, self.user = api, user_id, USERS[user_id]
        self.session_id = uuid.uuid4().hex[:8]
        self.tool_calls = self.sap_requests = 0
        self.requests_this_call = []

    def offered_tools(self) -> list[dict]:
        """Only the tools this user's roles allow. A read-only user never sees a draft tool."""
        return [t["definition"] for t in TOOLS.values() if t["roles"] & set(self.user["roles"])]

    def sap_get(self, path: str, params: dict) -> dict:
        if self.sap_requests >= MAX_SAP_REQUESTS:
            raise ToolError("The SAP request budget for this session is used up. Stop and report what you have.")
        self.sap_requests += 1
        self.requests_this_call.append(path)
        return self.api.get(path, params)

    def call(self, name: str, args: dict) -> dict:
        started, self.requests_this_call = time.perf_counter(), []
        entry = TOOLS.get(name)
        try:
            if entry is None or not entry["roles"] & set(self.user["roles"]):
                raise PermissionError(f"Tool {name} is not offered to this user.")
            self.tool_calls += 1
            if self.tool_calls > MAX_TOOL_CALLS:
                raise ToolError("Tool call limit for this session reached. Stop and summarize for the user.")
            clean = validate(entry["definition"]["parameters"], args)
            answer = {"ok": True, "result": entry["fn"](self, **clean)}
            outcome = "ok"
        except PermissionError as err:
            answer, outcome = {"ok": False, "error": str(err)}, "denied"
        except ToolError as err:
            answer, outcome = {"ok": False, "error": str(err)}, "tool_error"
        except SAPError as err:
            answer, outcome = {"ok": False, "error": f"SAP could not answer ({err}). Try again later "
                               "or tell the user the system is unavailable."}, "sap_error"
        self.audit(name, entry, args, outcome, answer, started)
        return answer

    def audit(self, name, entry, args, outcome, answer, started) -> None:
        """One line per tool call: who, what, with which arguments, what happened. No results."""
        line = {"ts": now(), "session": self.session_id, "user": self.user_id, "tool": name,
                "kind": entry["kind"] if entry else None, "args": args,
                "args_sha256": hashlib.sha256(json.dumps(args, sort_keys=True).encode()).hexdigest()[:16],
                "outcome": outcome, "sap_requests": self.requests_this_call, "backend": self.api.name,
                "ms": round((time.perf_counter() - started) * 1000)}
        result = answer.get("result") or {}
        if "orders" in result:
            line["rows_returned"] = len(result["orders"])
        if "draft_id" in result:
            line["draft_id"] = result["draft_id"]
        with AUDIT_LOG.open("a", encoding="utf-8") as f:
            f.write(json.dumps(line) + "\n")


def validate(schema: dict, args: dict) -> dict:
    """Check the model's arguments against the tool's schema before anything reaches SAP."""
    props = schema["properties"]
    unknown = set(args) - set(props)
    if unknown:
        raise ToolError(f"Unknown argument(s): {', '.join(sorted(unknown))}. Allowed: {', '.join(props)}.")
    for name in schema["required"]:
        if args.get(name) in (None, ""):
            raise ToolError(f"{name} is required. {props[name]['description']}")
    clean = {}
    for name, value in args.items():
        rule, types = props[name], props[name]["type"]
        types = types if isinstance(types, list) else [types]
        if value is None and "null" in types:
            continue
        if "integer" in types:
            if isinstance(value, bool) or not isinstance(value, int):
                raise ToolError(f"{name} must be a whole number. {rule['description']}")
            if not rule["minimum"] <= value <= rule["maximum"]:
                raise ToolError(f"{name} must be between {rule['minimum']} and {rule['maximum']}; you sent {value}.")
        elif not isinstance(value, str):
            raise ToolError(f"{name} must be text. {rule['description']}")
        else:
            value = value.strip()
            if "pattern" in rule and not re.fullmatch(rule["pattern"], value):
                raise ToolError(f"{name} has the wrong format: you sent {value[:30]!r}. {rule['description']}")
            if not rule.get("minLength", 0) <= len(value) <= rule.get("maxLength", 10_000):
                raise ToolError(f"{name} must be {rule.get('minLength', 0)} to {rule.get('maxLength', 10_000)} characters; "
                                f"you sent {len(value)}.")
        clean[name] = value
    return clean


# ------------------------------------------------------------------ commands

def show(label: str, answer: dict) -> None:
    print(f"\n> {label}")
    print("  " + json.dumps(answer, indent=2, ensure_ascii=False).replace("\n", "\n  "))


def find_other_org_order(api, user) -> str:
    """For the demo only: find an order outside the user's scope, by asking SAP directly."""
    orgs = " and ".join(f"SalesOrganization ne '{o}'" for o in user["sales_orgs"])
    rows = api.get("/A_SalesOrder", {"$filter": orgs, "$select": "SalesOrder", "$top": "1"}).get("results", [])
    return rows[0]["SalesOrder"] if rows else "9999999999"


def demo(api) -> None:
    ana = Session(api, "ana")
    print(f"Backend: {api.name}")
    print(f"Acting for: {ana.user['display']} (session {ana.session_id})")
    if isinstance(api, LiveSAP):
        print("Note: every sandbox call uses SAP's shared API key, not Ana's identity. Her scope is "
              "enforced only by this tool layer here; in production, SAP checks her own authorizations too.")
    print(f"Tools offered: {', '.join(t['name'] for t in ana.offered_tools())}")

    listed = ana.call("sales_order_list_blocked", {"limit": 5})
    show("1. sales_order_list_blocked limit=5", listed)
    orders = listed.get("result", {}).get("orders", [])
    first = orders[0]["sales_order"] if orders else "4711"

    show(f"2. sales_order_get sales_order='SO-{first}'  (a typical model mistake)",
         ana.call("sales_order_get", {"sales_order": f"SO-{first}"}))
    show(f"3. sales_order_get sales_order='{first}'", ana.call("sales_order_get", {"sales_order": first}))
    other = find_other_org_order(api, ana.user)
    show(f"4. sales_order_get sales_order='{other}'  (an order outside Ana's sales org)",
         ana.call("sales_order_get", {"sales_order": other}))
    show("5. sales_order_list_blocked limit=500  (out of range)",
         ana.call("sales_order_list_blocked", {"limit": 500}))

    why = "Customer paid the overdue invoice today; finance confirmed by phone."
    if orders:
        show(f"6. release_request_draft sales_order='{first}'",
             ana.call("release_request_draft", {"sales_order": first, "justification": why}))
        show(f"7. release_request_draft sales_order='{first}' again  (a retry)",
             ana.call("release_request_draft", {"sales_order": first, "justification": why}))
    else:
        print("\n> 6-7. skipped: no blocked orders were found, so there is nothing to draft.")

    kim = Session(api, "kim")
    print(f"\nActing for: {kim.user['display']} (session {kim.session_id})")
    print(f"Tools offered: {', '.join(t['name'] for t in kim.offered_tools())}")
    show(f"8. release_request_draft sales_order='{first}'  (not offered to an auditor)",
         kim.call("release_request_draft", {"sales_order": first, "justification": why}))
    print(f"\nAudit log: {AUDIT_LOG.name}. Drafts: {DRAFTS.name}. Nothing was sent to SAP except GET requests.")


def parse_pairs(pairs: list[str], name: str) -> dict:
    """Turn key=value words into arguments; numbers become integers where the schema expects them."""
    props = TOOLS[name]["definition"]["parameters"]["properties"] if name in TOOLS else {}
    args = {}
    for pair in pairs:
        key, sep, value = pair.partition("=")
        if not sep:
            sys.exit(f"Write arguments as key=value, for example sales_order=4711 (got {pair!r}).")
        types = props.get(key, {}).get("type", [])
        args[key] = int(value) if "integer" in types and value.lstrip("-").isdigit() else value
    return args


def audit_summary() -> None:
    if not AUDIT_LOG.exists():
        sys.exit("No audit log yet. Run the demo first.")
    lines = [json.loads(x) for x in AUDIT_LOG.read_text(encoding="utf-8").splitlines() if x.strip()]
    print(f"{len(lines)} tool calls in {AUDIT_LOG.name}\n")
    print(f"{'time (UTC)':20} {'user':5} {'tool':26} {'outcome':11} {'SAP calls':>9}")
    for x in lines[-15:]:
        print(f"{x['ts'][:19]:20} {x['user']:5} {x['tool']:26} {x['outcome']:11} {len(x['sap_requests']):>9}")
    counts = {}
    for x in lines:
        counts[x["outcome"]] = counts.get(x["outcome"], 0) + 1
    print("\nBy outcome: " + ", ".join(f"{k} {v}" for k, v in sorted(counts.items())))


def connect(sample: bool):
    if sample:
        return SampleSAP()
    try:
        from dotenv import load_dotenv
        load_dotenv()
    except ImportError:
        pass
    key = os.environ.get("SAP_API_KEY")
    if not key:
        sys.exit("SAP_API_KEY is not set. Add it to .env, or run with --sample.")
    return LiveSAP(key)


def main() -> None:
    parser = argparse.ArgumentParser(description="Read-only SAP sales order tools for agents, with controls.")
    parser.add_argument("command", choices=["tools", "demo", "call", "audit"])
    parser.add_argument("rest", nargs="*", help="for call: the tool name, then key=value arguments")
    parser.add_argument("--user", default="ana", help=f"who the agent acts for: {', '.join(USERS)}")
    parser.add_argument("--sample", action="store_true", help="use made-up data; no key or internet")
    a = parser.parse_args()

    if a.command == "tools":
        print(json.dumps(Session(SampleSAP(), a.user).offered_tools(), indent=2))
    elif a.command == "audit":
        audit_summary()
    else:
        api = connect(a.sample)
        if a.command == "demo":
            demo(api)
        else:
            if not a.rest:
                sys.exit("Name a tool, for example: call sales_order_get sales_order=4711")
            name, pairs = a.rest[0], a.rest[1:]
            show(f"{name} as {a.user}", Session(api, a.user).call(name, parse_pairs(pairs, name)))


if __name__ == "__main__":
    main()

python unit09/sap_tools.py tools --user ana

[
  {
    "name": "sales_order_list_blocked",
    "description": "List the user's sales orders that have a delivery block, ...",
    "parameters": {
      "type": "object",
      "properties": {
        "customer": {

python unit09/sap_tools.py tools --user kim

python unit09/sap_tools.py demo --sample

Backend: made-up sample data
Acting for: Ana, order clerk, sales org 1010 (session 14432eb4)
Tools offered: sales_order_list_blocked, sales_order_get, release_request_draft

> 1. sales_order_list_blocked limit=5
  {
    "ok": true,
    "result": {
      "orders": [
        {
          "sales_order": "4718",
          ...
      "blocked_found": 3,
      "orders_scanned": 4
    }
  }

> 2. sales_order_get sales_order='SO-4718'  (a typical model mistake)
  {
    "ok": false,
    "error": "sales_order has the wrong format: you sent 'SO-4718'. Sales order number, digits only, e.g. '4711'. Remove prefixes like 'SO-'."
  }

> 4. sales_order_get sales_order='4801'  (an order outside Ana's sales org)
  {
    "ok": false,
    "error": "Sales order 4801 does not exist or you may not see it. ..."
  }

> 5. sales_order_list_blocked limit=500  (out of range)
  {
    "ok": false,
    "error": "limit must be between 1 and 20; you sent 500."
  }

> 6. release_request_draft sales_order='4718'
  ... "draft_id": "D-0001", "status": "awaiting_approval", "duplicate": false ...

> 7. release_request_draft sales_order='4718' again  (a retry)
  ... "draft_id": "D-0001", "status": "awaiting_approval", "duplicate": true ...

Acting for: Kim, auditor, sales org 1010 (session 42368ad7)
Tools offered: sales_order_list_blocked, sales_order_get

> 8. release_request_draft sales_order='4718'  (not offered to an auditor)
  {
    "ok": false,
    "error": "Tool release_request_draft is not offered to this user."
  }

python unit09/sap_tools.py audit

8 tool calls in tool_audit.jsonl

time (UTC)           user  tool                       outcome     SAP calls
2026-10-06T03:33:31  ana   sales_order_list_blocked   ok                  1
2026-10-06T03:33:31  ana   sales_order_get            tool_error          0
2026-10-06T03:33:31  ana   sales_order_get            ok                  2
2026-10-06T03:33:31  ana   sales_order_get            tool_error          1
2026-10-06T03:33:31  ana   sales_order_list_blocked   tool_error          0
2026-10-06T03:33:31  ana   release_request_draft      ok                  1
2026-10-06T03:33:31  ana   release_request_draft      ok                  1
2026-10-06T03:33:31  kim   release_request_draft      denied              0

By outcome: denied 1, ok 4, tool_error 3

python unit09/sap_tools.py call sales_order_get sales_order=4711 --sample
python unit09/sap_tools.py call sales_order_list_blocked customer=17100001 --user ben --sample
python unit09/sap_tools.py call sales_order_get sales_order=4711 color=red --sample

Note: every sandbox call uses SAP's shared API key, not Ana's identity. Her scope is enforced only by this tool layer here; in production, SAP checks her own authorizations too.

git add unit09/sap_tools.py .gitignore
git commit -m "Unit 9: SAP tools with a gateway"

# SKETCH: runs only in the approval step, never as a tool the model can call.
def execute_approved(session, base, draft, approval):
    assert approval["draft_id"] == draft["draft_id"] and approval["decision"] == "approve"
    # 1. Read again: fetch a CSRF token and the record's current version (ETag).
    r = session.get(f"{base}/A_SalesOrder('{draft['sales_order']}')",
                    headers={"X-CSRF-Token": "Fetch", "Accept": "application/json"}, timeout=30)
    token, etag = r.headers["X-CSRF-Token"], r.headers.get("ETag")
    if not etag:
        raise RuntimeError("No ETag: can't prove the order is unchanged. Ask the approver to look again.")
    # 2. Change with If-Match so it fails if the order changed since the approver looked.
    #    RequestID (a 32-character GUID) and RepeatabilityCreation let a service with idempotent
    #    settings answer a repeat without running it twice; check the timestamp format your system expects.
    resp = session.post(f"{base}/releaseApprovalRequest", params={"SalesOrder": f"'{draft['sales_order']}'"},
                        headers={"X-CSRF-Token": token, "If-Match": etag,
                                 "RequestID": hashlib.md5(draft["idempotency_key"].encode()).hexdigest(),
                                 "RepeatabilityCreation": draft["created_at"]}, timeout=30)
    audit(draft, approval, resp.status_code)   # who asked, who approved, what SAP answered
    return resp.status_code