synth-agent-sdk 2.0.0__tar.gz → 2.2.0__tar.gz

synth_agent_sdk-2.2.0/.dockerignore

@@ -0,0 +1,27 @@
+.git/
+.github/
+.hypothesis/
+.bedrock_agentcore/
+*.env
+.env*
+**/.aws/
+**/__pycache__/
+**/*.pyc
+**/*.pyo
+*.egg-info/
+dist/
+build/
+.coverage
+htmlcov/
+.pytest_cache/
+node_modules/
+Legal Team/
+agent/
+tests/
+docs/
+*.log
+agentcore.yaml
+.bedrock_agentcore.yaml
+**/.synth/
+.kiro/
+Synth Website/

synth_agent_sdk-2.2.0/.github/CODEOWNERS

@@ -0,0 +1,34 @@
+# Synth SDK CODEOWNERS
+#
+# This file assigns mandatory reviewers to PRs touching the given
+# paths. See https://docs.github.com/en/repositories/managing-your-
+# repositories-settings-and-features/customizing-your-repository/
+# about-code-owners for syntax.
+
+# ---------------------------------------------------------------------------
+# UI surfaces — Task 8.2 of telemetry-and-ui-architecture spec (R6.4).
+#
+# The Dev Space UI server and its assets are thin-presenter surfaces
+# per design §2.2 and the AgentCore Native Execution Principle
+# (rule 9). Every change to these paths must be reviewed by the
+# observability team so UI changes that would re-introduce
+# authoritative state caching or bypass the `_sse_emit` provenance
+# funnel are caught at review time.
+# ---------------------------------------------------------------------------
+
+synth/cli/_ui_assets/                    @observability-team
+synth/cli/_ui_assets/provenance.py       @observability-team
+synth/cli/_ui_assets/agentcore_history.py @observability-team
+synth/cli/_ui_assets/server.py           @observability-team
+synth/cli/_ui_assets/static/             @observability-team
+
+# ---------------------------------------------------------------------------
+# Observability sinks — Tasks 2.x, 3.x, 4.x (R2, R3, R4).
+#
+# First-party sinks share a stats() contract (NFR.4) and a set of
+# wire-format invariants that the observability team owns.
+# ---------------------------------------------------------------------------
+
+synth/observability/                     @observability-team
+synth/tracing/attributes.py              @observability-team
+synth/cli/_doc_gen/                      @observability-team

synth_agent_sdk-2.2.0/.github/workflows/observability-doc-idempotence.yml

@@ -0,0 +1,52 @@
+name: Observability Doc Idempotence
+
+# Task 7.4 of the telemetry-and-ui-architecture spec.
+#
+# Re-runs the deterministic observability HTML generator and asserts
+# the committed `Synth Website/docs/observability.html` is identical
+# to what the generator produces now. If anyone edits the span
+# dataclasses in `synth/tracing/attributes.py` or the generator
+# itself without regenerating the page, this job fails the PR with
+# a clear "run the generator" message.
+
+on:
+  pull_request:
+    paths:
+      - 'synth/cli/_doc_gen/**'
+      - 'synth/tracing/attributes.py'
+      - 'Synth Website/docs/observability.html'
+
+jobs:
+  check:
+    name: Verify observability.html is up to date
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+
+    steps:
+      - name: Checkout PR
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install SDK (editable)
+        # The generator imports from ``synth.tracing.attributes``; an
+        # editable install is the fastest way to make that import
+        # resolve without shipping a wheel.
+        run: pip install --quiet -e .
+
+      - name: Regenerate observability.html
+        run: python -m synth.cli._doc_gen.observability_html
+
+      - name: Assert no diff
+        run: |
+          if ! git diff --exit-code -- 'Synth Website/docs/observability.html'; then
+            echo "::error::Synth Website/docs/observability.html is out of"
+            echo "::error::date relative to the generator. Run"
+            echo "::error::'python -m synth.cli._doc_gen.observability_html'"
+            echo "::error::locally, commit the regenerated HTML, and"
+            echo "::error::push again."
+            exit 1
+          fi

synth_agent_sdk-2.2.0/.github/workflows/pricing-feed-validation.yml

@@ -0,0 +1,102 @@
+name: ci-pricing-feed-validation
+
+# Anchored by Task 17.2 of
+# .kiro/specs/active/foundational/cost-and-pricing-accuracy/tasks.md.
+#
+# Runs on every PR that touches the pricing pipeline: schema-validates
+# the bundled feed (Req 1.3) and runs the refresh script in dry-run
+# mode to produce a delta summary for PR reviewers (Req 10.7).
+
+on:
+  pull_request:
+    paths:
+      - "synth/pricing/**"
+      - "scripts/refresh_pricing_feed.py"
+      - "scripts/aws_bulk_parser.py"
+      - "scripts/litellm_parser.py"
+      - "synth/pricing/data/sources/**"
+  workflow_dispatch: {}
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  validate-feed:
+    name: Validate bundled pricing feed + dry-run delta
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install SDK with pricing-refresh extra
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e '.[pricing-refresh]'
+
+      - name: Run bundled-feed schema validation
+        run: |
+          python -m pytest tests/unit/test_pricing_feed_bundled.py -v --tb=short
+
+      - name: Run refresh script in dry-run mode
+        id: dry_run
+        continue-on-error: true
+        run: |
+          set +e
+          OUTPUT_FILE="/tmp/refresh_dry_run_output.txt"
+          python -m scripts.refresh_pricing_feed --dry-run 2>&1 | tee "$OUTPUT_FILE"
+          RC=${PIPESTATUS[0]}
+          echo "exit_code=$RC" >> "$GITHUB_OUTPUT"
+          # Extract the "Pricing feed refresh — delta summary" block
+          # by anchoring on the header and the trailing blank line.
+          awk '/Pricing feed refresh/,/^$/' "$OUTPUT_FILE" > /tmp/delta_summary.txt || true
+          {
+            echo "delta_summary<<DELTA_EOF"
+            cat /tmp/delta_summary.txt
+            echo "DELTA_EOF"
+          } >> "$GITHUB_OUTPUT"
+          exit $RC
+
+      - name: Post delta summary as PR comment
+        if: ${{ github.event_name == 'pull_request' }}
+        uses: actions/github-script@v7
+        env:
+          DELTA_SUMMARY: ${{ steps.dry_run.outputs.delta_summary }}
+          DRY_RUN_EXIT: ${{ steps.dry_run.outputs.exit_code }}
+        with:
+          script: |
+            const summary = process.env.DELTA_SUMMARY || "(no delta summary captured)";
+            const exitCode = process.env.DRY_RUN_EXIT || "unknown";
+            const status = exitCode === "0"
+              ? "✅ Dry-run passed"
+              : `❌ Dry-run failed (exit ${exitCode})`;
+            const body = [
+              "## Pricing feed refresh — dry-run delta",
+              "",
+              status,
+              "",
+              "```",
+              summary,
+              "```",
+              "",
+              "_Posted by ci-pricing-feed-validation (Task 17.2). "
+              + "Reviewers: confirm the model/resource deltas against "
+              + "the PR's intended scope before merge._",
+            ].join("\n");
+            await github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+              body,
+            });
+
+      - name: Fail job if dry-run failed
+        if: ${{ steps.dry_run.outputs.exit_code != '0' }}
+        run: |
+          echo "::error::Refresh script dry-run failed with exit code ${{ steps.dry_run.outputs.exit_code }}. See the job log or PR comment for the delta summary."
+          exit 1

synth_agent_sdk-2.2.0/.github/workflows/pricing-freshness.yml

@@ -0,0 +1,129 @@
+name: ci-pricing-freshness
+
+# Anchored by Task 17.1 of
+# .kiro/specs/active/foundational/cost-and-pricing-accuracy/tasks.md.
+#
+# Fails the build when the bundled pricing feed is older than
+# 120 days (Req 2.3 — buffer over the 90-day release target) or
+# when an entry in synth/pricing/data/sources/overrides.json has a
+# sunset_date in the past (Req 10.4).
+
+on:
+  push:
+    branches: [main]
+  schedule:
+    # Nightly at 02:30 UTC so a newly-stale feed is caught before
+    # the next release cut.
+    - cron: "30 2 * * *"
+  workflow_dispatch: {}
+
+permissions:
+  contents: read
+
+jobs:
+  check-freshness:
+    name: Check bundled pricing feed freshness
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Check bundled-feed age
+        shell: python {0}
+        run: |
+          import datetime as _dt
+          import glob
+          import json
+          import os
+          import re
+          import sys
+
+          FEED_GLOB = "synth/pricing/data/pricing_feed_*.json"
+          MAX_AGE_DAYS = 120
+
+          matches = sorted(glob.glob(FEED_GLOB))
+          if not matches:
+              print(f"::error::No bundled pricing feed found under {FEED_GLOB}. "
+                    f"Run 'scripts/refresh_pricing_feed.py' to generate one.")
+              sys.exit(1)
+          if len(matches) > 1:
+              print(f"::error::Multiple bundled pricing feeds found: {matches}. "
+                    f"A release should contain exactly one; delete stale feeds.")
+              sys.exit(1)
+
+          feed_path = matches[0]
+          with open(feed_path, "r", encoding="utf-8") as f:
+              feed = json.load(f)
+
+          pricing_date_str = feed["pricing_data_date"]
+          pricing_date = _dt.date.fromisoformat(pricing_date_str)
+          today = _dt.datetime.now(_dt.UTC).date()
+          age_days = (today - pricing_date).days
+
+          print(f"Bundled pricing feed: {feed_path}")
+          print(f"  pricing_data_date: {pricing_date_str}")
+          print(f"  age (days):        {age_days}")
+          print(f"  max allowed:       {MAX_AGE_DAYS}")
+
+          if age_days > MAX_AGE_DAYS:
+              print(f"::error file={feed_path}::"
+                    f"Bundled pricing feed is {age_days} days old; "
+                    f"exceeds the {MAX_AGE_DAYS}-day cap (Req 2.3). "
+                    f"Run 'python -m scripts.refresh_pricing_feed' to regenerate, "
+                    f"then commit the new feed file.")
+              sys.exit(1)
+
+          print(f"::notice file={feed_path}::"
+                f"Bundled pricing feed is {age_days} days old (under "
+                f"{MAX_AGE_DAYS}-day cap).")
+
+      - name: Check overrides sunset dates
+        shell: python {0}
+        run: |
+          import datetime as _dt
+          import json
+          import sys
+
+          OVERRIDES_PATH = "synth/pricing/data/sources/overrides.json"
+
+          with open(OVERRIDES_PATH, "r", encoding="utf-8") as f:
+              overrides = json.load(f)
+
+          overrides.pop("_schema_comment", None)
+          today = _dt.datetime.now(_dt.UTC).date()
+
+          expired: list[tuple[str, str, str]] = []
+          for section in ("models", "resources"):
+              entries = overrides.get(section, {}) or {}
+              for key, entry in entries.items():
+                  if not isinstance(entry, dict):
+                      continue
+                  sunset_raw = entry.get("sunset_date")
+                  if not isinstance(sunset_raw, str):
+                      continue
+                  try:
+                      sunset = _dt.date.fromisoformat(sunset_raw)
+                  except ValueError:
+                      print(f"::error file={OVERRIDES_PATH}::"
+                            f"Override {section}['{key}'] has invalid "
+                            f"sunset_date {sunset_raw!r}.")
+                      sys.exit(1)
+                  if sunset < today:
+                      expired.append((section, key, sunset_raw))
+
+          if expired:
+              for section, key, sunset_raw in expired:
+                  days_expired = (today - _dt.date.fromisoformat(sunset_raw)).days
+                  print(f"::error file={OVERRIDES_PATH}::"
+                        f"Override {section}['{key}'] expired "
+                        f"{days_expired} days ago (sunset_date={sunset_raw}). "
+                        f"Either extend the sunset_date or remove the override.")
+              sys.exit(1)
+
+          print(f"::notice file={OVERRIDES_PATH}::"
+                f"All overrides are within their sunset_date windows.")

synth_agent_sdk-2.2.0/.github/workflows/spec-metadata-lint.yml

@@ -0,0 +1,137 @@
+name: Spec Metadata Lint
+
+# Task 6.2 — Telemetry and UI Architecture spec R7.1 / R7.3 / R7.4.
+# Validates that every `.kiro/specs/**/requirements.md` modified in a PR
+# carries the metadata header required by
+# `.kiro/steering/Spec Metadata Convention.md`. Uses the
+# `--check --file …` mode added to `regenerate_spec_index.py` in Task 6.1
+# so the validator only inspects the PR's changed files.
+
+on:
+  pull_request:
+    paths:
+      - '.kiro/specs/**/requirements.md'
+
+jobs:
+  lint:
+    name: Validate spec metadata headers
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+
+    steps:
+      - name: Checkout PR
+        uses: actions/checkout@v4
+        with:
+          # Fetch two commits so `git diff HEAD^ HEAD` resolves the
+          # changed-file list below.
+          fetch-depth: 2
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install PyYAML
+        # The validator is self-contained apart from PyYAML (used by
+        # the companion `update_cross_references.py` script imported
+        # indirectly). No SDK install needed — R7.4 calls for
+        # completion inside 30 seconds on a 5-file diff.
+        run: pip install --quiet pyyaml
+
+      - name: Collect changed requirements.md files
+        id: changed
+        run: |
+          # Prefer GitHub's PR base-ref resolution; fall back to
+          # `HEAD^` when the action is re-run outside the PR context.
+          if [ -n "$GITHUB_BASE_REF" ]; then
+            git fetch --depth=1 origin "$GITHUB_BASE_REF"
+            base="origin/$GITHUB_BASE_REF"
+          else
+            base="HEAD^"
+          fi
+          files=$(git diff --name-only --diff-filter=AMR "$base" HEAD \
+                    -- '.kiro/specs/**/requirements.md' || true)
+          if [ -z "$files" ]; then
+            echo "no changed requirements.md files — skipping."
+            echo "files=" >> "$GITHUB_OUTPUT"
+          else
+            echo "$files"
+            # Emit a multi-line output for the next step.
+            {
+              echo "files<<EOF"
+              echo "$files"
+              echo "EOF"
+            } >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Validate metadata (timed)
+        id: validate
+        if: steps.changed.outputs.files != ''
+        run: |
+          # Task 6.4 — workflow completion time check. The validator
+          # itself runs inside `time`; we fail the step if it ever
+          # takes longer than 30s on a 5-file diff (R7.4 / NFR.3).
+          args=()
+          while IFS= read -r file; do
+            [ -z "$file" ] && continue
+            args+=("--file" "$file")
+          done <<< "${{ steps.changed.outputs.files }}"
+
+          start=$(date +%s)
+          set +e
+          # Capture stderr so we can post it verbatim to the PR comment
+          # (R7.3 / Task 6.5 — "actionable field list").
+          python .kiro/scripts/regenerate_spec_index.py \
+            --check "${args[@]}" 2> /tmp/lint-stderr.log
+          status=$?
+          set -e
+          end=$(date +%s)
+          elapsed=$((end - start))
+
+          echo "elapsed=$elapsed" >> "$GITHUB_OUTPUT"
+          echo "status=$status" >> "$GITHUB_OUTPUT"
+
+          if [ "$elapsed" -gt 30 ]; then
+            echo "::error::Spec metadata lint exceeded 30s cap (actual: ${elapsed}s)."
+            exit 1
+          fi
+
+          if [ "$status" -ne 0 ]; then
+            cat /tmp/lint-stderr.log
+            exit "$status"
+          fi
+
+      - name: Post actionable failure comment
+        if: failure() && steps.validate.outputs.status != '0'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const fs = require('fs');
+            let body;
+            try {
+              body = fs.readFileSync('/tmp/lint-stderr.log', 'utf8');
+            } catch (e) {
+              body = '(validator produced no stderr output)';
+            }
+            const link = (
+              '.kiro/steering/Spec Metadata Convention.md'
+            );
+            const msg = [
+              '### Spec metadata validation failed',
+              '',
+              'The `regenerate_spec_index.py --check` validator reported:',
+              '',
+              '```',
+              body.trim(),
+              '```',
+              '',
+              `See [${link}](${link}) for the required metadata header format.`,
+              '',
+              'Run `python .kiro/scripts/regenerate_spec_index.py --check` locally to reproduce.',
+            ].join('\n');
+            await github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+              body: msg,
+            });

synth_agent_sdk-2.2.0/.gitignore

@@ -0,0 +1,68 @@
+# Python build artifacts
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+*.egg-info/
+*.egg
+dist/
+build/
+*.whl
+*.tar.gz
+MANIFEST
+
+# Virtual environments
+.venv/
+venv/
+env/
+.env
+
+# Test & coverage
+.hypothesis/
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+*.cover
+
+# IDE & editor
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Local dev state
+.synth/
+.bedrock_agentcore/
+*.log
+
+# CDK build artifacts
+synth-ui-deploy/cdk.out/
+synth-ui-deploy/cdk.out.*/
+synth-ui-deploy/.venv/
+synth-ui-deploy/team-configs/
+
+# Secrets & credentials
+.env
+*.env
+.aws/
+
+# macOS
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Jupyter
+.ipynb_checkpoints/
+*.ipynb
+
+# Type checking
+.mypy_cache/
+.dmypy.json
+.pytype/
+
+# Docs build
+docs/_build/
+site/