talkpipe-agents 0.1.0__tar.gz

talkpipe_agents-0.1.0/.gitea/default_merge_message/MERGE_TEMPLATE.md

@@ -0,0 +1 @@
+Merge branch '${HeadBranch}': ${PullRequestTitle}

talkpipe_agents-0.1.0/.gitea/default_merge_message/SQUASH_TEMPLATE.md

@@ -0,0 +1 @@
+${PullRequestTitle}

talkpipe_agents-0.1.0/.github/ISSUE_TEMPLATE/release-checklist.md

@@ -0,0 +1,20 @@
+---
+name: Release Checklist
+about: Steps for doing a new release (see RELEASING.md for detail)
+title: Release vX.Y.Z
+labels: ''
+assignees: ''
+
+---
+
+Assumes the TalkPipe release this depends on is already out and working.
+
+- [ ] `main` up to date, CI green, working tree clean
+- [ ] `talkpipe>=…` floor in `pyproject.toml` matches what this release needs (`uv lock` if changed)
+- [ ] CHANGELOG: `## Unreleased` → `## X.Y.Z (YYYY-MM-DD)`, fresh empty section above; merged via MR
+- [ ] Build the wheel and install it into a **new** virtual environment; `chatterlang_script` runs an `llmAgent[...]` step against a real model (Ollama or another configured provider)
+- [ ] Anything found: fix via MR, re-test
+- [ ] Tag the merge commit on `main` (`git tag -a vX.Y.Z -m vX.Y.Z`) and push the tag; advance `stable` for a full release
+- [ ] Push `main`, the tag, and `stable` to GitHub
+- [ ] Publish the release on GitHub (pre-release for alphas/betas/rcs); watch `publish-package` finish
+- [ ] Verify: `pip install talkpipe-agents==X.Y.Z` in a fresh venv, `python -c "import talkpipe_agents; print(talkpipe_agents.__version__)"` prints `X.Y.Z`

talkpipe_agents-0.1.0/.github/SECURITY.md

@@ -0,0 +1,47 @@
+# Security Policy
+
+## Supported Versions
+
+Security fixes go into the latest release only.
+
+| Version | Supported          |
+| ------- | ------------------ |
+| Latest  | :white_check_mark: |
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability in talkpipe-agents, please report
+it responsibly:
+
+1. **Do not** open a public GitHub issue for it.
+2. Email the report to tlbauer@sandia.gov.
+3. Include a description of the vulnerability, steps to reproduce it, the
+   potential impact, and a suggested fix if you have one.
+
+A vulnerability in the agent's tool suite (for example a tool that reads
+files or fetches URLs doing more than its documentation says) counts; one in
+[talkpipe](https://github.com/sandialabs/talkpipe) or in
+[Strands Agents](https://github.com/strands-agents/sdk-python) belongs to
+that project.
+
+### What to Expect
+
+- **Response**: we aim to acknowledge receipt within 2 business days.
+- **Assessment**: an initial assessment within 5 business days.
+- **Updates**: progress updates every 7 days until resolution.
+- **Disclosure**: public disclosure is coordinated with the reporter once a
+  fix is released.
+
+### Security Measures
+
+- Dependency scanning with Safety and static analysis with Bandit on every
+  CI run, both gating the build.
+- Static code analysis with CodeQL.
+- Automated dependency updates via Dependabot.
+- Declared dependency floors are security minimums: the lowest release of
+  each dependency with no known advisory.
+
+### Acknowledgments
+
+Researchers who responsibly disclose vulnerabilities are acknowledged in the
+release notes unless they prefer to remain anonymous.

talkpipe_agents-0.1.0/.github/dependabot.yml

@@ -0,0 +1,38 @@
+version: 2
+updates:
+  # Enable version updates for Python dependencies
+  - package-ecosystem: "pip"
+    directory: "/"
+    target-branch: "main"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 10
+    reviewers:
+      - "tlbauer2"
+    assignees:
+      - "tlbauer2"
+    commit-message:
+      prefix: "deps"
+      prefix-development: "dev-deps"
+      include: "scope"
+
+  # Enable version updates for GitHub Actions
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    target-branch: "main"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+    reviewers:
+      - "tlbauer2"
+    assignees:
+      - "tlbauer2"
+    commit-message:
+      prefix: "ci"
+      include: "scope"
+    # CodeQL refuses to run when its steps are on different versions, so
+    # update all github/codeql-action steps in one PR.
+    groups:
+      codeql-action:
+        patterns:
+          - "github/codeql-action*"

talkpipe_agents-0.1.0/.github/workflows/ci-cd.yml

@@ -0,0 +1,372 @@
+name: CI/CD Pipeline
+
+on:
+  push:
+    branches: [ main, 'bugfix/**', 'feature/**', 'chore/**' ]
+    tags: [ 'v*' ]   # a version tag runs the gate and then publish-registry
+  pull_request:
+    branches: [ main, 'bugfix/**', 'feature/**', 'chore/**' ]
+  release:
+    types: [ published ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.11', '3.12', '3.13']
+
+    steps:
+    - uses: actions/checkout@v7
+      with:
+        fetch-depth: 0   # setuptools_scm derives the version from tags
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v7
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Cache pip dependencies
+      uses: actions/cache@v6
+      with:
+        path: ~/.cache/pip
+        key: ${{ runner.os }}-pip-${{ hashFiles('pyproject.toml') }}
+        restore-keys: |
+          ${{ runner.os }}-pip-
+
+    - name: Install dependencies
+      run: |
+        # Install into a project venv rather than the interpreter itself. On a
+        # self-hosted runner /opt/hostedtoolcache is a volume shared by every
+        # job, so installing there leaks packages between repos.
+        python -m venv .venv
+        echo "$PWD/.venv/bin" >> "$GITHUB_PATH"
+        .venv/bin/python -m pip install --upgrade pip
+        .venv/bin/pip install -e .[dev]
+
+    - name: Run tests with coverage
+      run: |
+        pytest --cov=src --cov-report=xml --cov-report=html
+
+    - name: Upload coverage to Codecov
+      # the action uploads to codecov.io on behalf of a GitHub repo; there is
+      # no equivalent when this runs on Gitea
+      if: matrix.python-version == '3.11' && github.server_url == 'https://github.com'
+      uses: codecov/codecov-action@v7
+      with:
+        files: ./coverage.xml
+        flags: unittests
+
+  lint:
+    # Ruff (lint + format) and mypy gate the build; there is no advisory
+    # pass and nothing here may swallow a failure. Local equivalent:
+    # `pre-commit run --all-files`, or the three commands below.
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v7
+      with:
+        fetch-depth: 0   # setuptools_scm derives the version from tags
+
+    - name: Set up Python
+      uses: actions/setup-python@v7
+      with:
+        python-version: '3.11'
+
+    - name: Install dependencies
+      run: |
+        # see the note on the test job's install step
+        python -m venv .venv
+        echo "$PWD/.venv/bin" >> "$GITHUB_PATH"
+        .venv/bin/python -m pip install --upgrade pip
+        .venv/bin/pip install -e .[dev]
+
+    - name: Ruff lint
+      run: ruff check --output-format=github .
+
+    - name: Ruff format check
+      run: ruff format --check --diff .
+
+    - name: mypy
+      run: mypy
+
+  package:
+    # Build the sdist and wheel the way a release would, then install the
+    # wheel into a clean venv and prove it works as a talkpipe plugin.
+    # Without this a broken wheel is only discovered by the publish jobs, at
+    # release time. Host-neutral: runs unchanged on any Actions-compatible
+    # runner.
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v7
+      with:
+        fetch-depth: 0   # setuptools_scm derives the version from tags
+
+    - name: Set up Python
+      uses: actions/setup-python@v7
+      with:
+        python-version: '3.11'
+
+    - name: Build sdist and wheel
+      run: |
+        # see the note on the test job's install step
+        python -m venv .venv
+        echo "$PWD/.venv/bin" >> "$GITHUB_PATH"
+        .venv/bin/python -m pip install --upgrade pip
+        .venv/bin/pip install build twine
+        .venv/bin/python -m build
+        .venv/bin/twine check dist/*
+
+    - name: Install the wheel into a clean venv and smoke-test it
+      run: |
+        python -m venv .smoke
+        .smoke/bin/python -m pip install --upgrade pip
+        # pytest only so the pytest11 entry point (the scripted_model
+        # fixture) can be loaded below; it is what imports that module.
+        .smoke/bin/pip install dist/*.whl pytest
+        # The version metadata must resolve from the installed wheel.
+        .smoke/bin/python -c "import talkpipe_agents; print(talkpipe_agents.__version__)"
+        # The plugin contract: importing talkpipe alone -- no import of
+        # talkpipe_agents -- must register the segments, and every declared
+        # entry point must resolve in the installed wheel.
+        .smoke/bin/python - <<'PY'
+        from importlib.metadata import entry_points
+
+        import talkpipe  # noqa: F401
+        from talkpipe.chatterlang import registry
+
+        for name in ("llmAgent", "scriptTool"):
+            if name not in registry.segment_registry.available_names:
+                raise SystemExit(f"{name} is not registered after importing talkpipe")
+        bad = []
+        for group in ("talkpipe.plugins", "pytest11"):
+            for ep in entry_points(group=group):
+                try:
+                    ep.load()
+                except Exception as exc:  # noqa: BLE001
+                    bad.append(f"{group}:{ep.name} -> {exc!r}")
+        if bad:
+            raise SystemExit("unresolvable entry points:\n" + "\n".join(bad))
+        print("plugin registers and all entry points resolve")
+        PY
+
+  lockfile-check:
+    # uv.lock is a development convenience only -- CI installs with pip on
+    # purpose (see README, "Development environment"). This job installs
+    # nothing from the lock; it only fails when uv.lock has drifted out of
+    # sync with pyproject.toml, so the committed lock cannot go stale
+    # unnoticed.
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v7
+      with:
+        fetch-depth: 0   # setuptools_scm derives the version from tags
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v7
+
+    - name: Check uv.lock is in sync with pyproject.toml
+      run: uv lock --check
+
+  security-scan:
+    runs-on: ubuntu-latest
+    needs: [test, lint]
+    env:
+      SAFETY_API_KEY: ${{ secrets.SAFETY_API_KEY }}
+
+    steps:
+    - uses: actions/checkout@v7
+      with:
+        fetch-depth: 0   # setuptools_scm derives the version from tags
+
+    - name: Set up Python
+      uses: actions/setup-python@v7
+      with:
+        python-version: '3.11'
+
+    - name: Install dependencies for security scan
+      run: |
+        # see the note on the test job's install step
+        python -m venv .venv
+        echo "$PWD/.venv/bin" >> "$GITHUB_PATH"
+        # Safety scans the whole installed environment, including the
+        # setuptools that `python -m venv` seeds on Python 3.11, which is not a
+        # project dependency and is not touched by upgrading pip. Upgrade it
+        # past CVE-2026-59890 (fixed in 83.0.0) so the scan reports only
+        # findings the project can act on.
+        .venv/bin/python -m pip install --upgrade pip "setuptools>=83"
+        # No extras: `dev` also installs the scanners.
+        .venv/bin/pip install -e .
+        # The scanners get a venv of their own, outside the workspace, so the
+        # scan covers what the project installs and not the scanners' own
+        # dependencies (safety brings in nltk, which nothing here depends on).
+        python -m venv "$RUNNER_TEMP/scan-tools"
+        echo "$RUNNER_TEMP/scan-tools/bin" >> "$GITHUB_PATH"
+        "$RUNNER_TEMP/scan-tools/bin/python" -m pip install --upgrade pip
+        "$RUNNER_TEMP/scan-tools/bin/pip" install bandit safety
+
+    - name: Run Bandit security scan
+      run: |
+        bandit -c pyproject.toml -r src/ -f json -o bandit-report.json
+        bandit -c pyproject.toml -r src/ -f txt
+
+    - name: Run Safety dependency scan
+      run: |
+        if [ -n "${SAFETY_API_KEY:-}" ]; then
+          # Authenticated: the commercial database, gated by .safety-policy.yml.
+          safety scan --save-as json safety-report.json
+          safety scan
+        else
+          # Gitea withholds every secret from pull_request runs -- it flags AGit
+          # merge requests as fork pull requests even when head and base are the
+          # same repo. Rather than skip the scan there (silently unscanned) or
+          # fail it for lack of auth, fall back to the free database. This still
+          # fails the build on a known vulnerability; the data is just staler
+          # than the authenticated scan that gates pushes.
+          echo "SAFETY_API_KEY unavailable; falling back to 'safety check' (free database)."
+          # `check` is the legacy command and the only one that runs without an
+          # account. It rejects .safety-policy.yml because that file is v3.0 and
+          # only `scan` parses v3, so run it from a directory holding no policy
+          # file. Left to itself it scans the venv it runs from, so hand it
+          # the project venv's packages instead.
+          report="$PWD/safety-report.json"
+          workdir="$(mktemp -d)"
+          .venv/bin/python -m pip freeze --exclude-editable > "$workdir/installed.txt"
+          (cd "$workdir" && safety check --stdin --save-json "$report" < installed.txt)
+        fi
+
+    - name: Upload security scan results
+      uses: actions/upload-artifact@v7
+      # upload-artifact v4+ refuses to run when the server isn't github.com
+      if: always() && github.server_url == 'https://github.com'
+      with:
+        name: security-reports
+        path: |
+          bandit-report.json
+          safety-report.json
+
+  codeql-analysis:
+    name: CodeQL Analysis
+    runs-on: ubuntu-latest
+    # needs GitHub's code-scanning API, which Gitea does not implement
+    if: github.server_url == 'https://github.com'
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+
+    strategy:
+      fail-fast: false
+      matrix:
+        language: [ 'python' ]
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v7
+      with:
+        fetch-depth: 0   # setuptools_scm derives the version from tags
+
+    - name: Initialize CodeQL
+      uses: github/codeql-action/init@v4
+      with:
+        languages: ${{ matrix.language }}
+
+    - name: Autobuild
+      uses: github/codeql-action/autobuild@v4
+
+    - name: Perform CodeQL Analysis
+      uses: github/codeql-action/analyze@v4
+
+  publish-registry:
+    # Pushing a version tag (vX.Y.Z) to a self-hosted server uploads the
+    # sdist and wheel to that server's PyPI package registry, from where
+    # `pip install` on the same network can fetch them. The registry URL is
+    # derived from the server running the job, so nothing about the host is
+    # recorded here.
+    #
+    # Never runs on github.com: there, publish-package below uploads to PyPI
+    # from a published release instead. To stop publishing to the local
+    # registry (once consumers install from PyPI), set the repository
+    # Actions variable PUBLISH_REGISTRY to `false`; no workflow change needed.
+    # `push` only: a release published for the same tag would otherwise run
+    # this job a second time and fail on the already-uploaded version.
+    runs-on: ubuntu-latest
+    needs: [test, lint, package, security-scan]
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v') && github.server_url != 'https://github.com' && vars.PUBLISH_REGISTRY != 'false'
+
+    steps:
+    - uses: actions/checkout@v7
+      with:
+        fetch-depth: 0   # setuptools_scm derives the version from tags
+
+    - name: Set up Python
+      uses: actions/setup-python@v7
+      with:
+        python-version: '3.11'
+
+    - name: Build sdist and wheel
+      run: |
+        # see the note on the test job's install step
+        python -m venv .venv
+        echo "$PWD/.venv/bin" >> "$GITHUB_PATH"
+        .venv/bin/python -m pip install --upgrade pip
+        .venv/bin/pip install build twine
+        .venv/bin/python -m build
+        .venv/bin/twine check dist/*
+        # The built version must be the tag's: anything else (a .devN or
+        # +dirty version) means the checkout is not the tagged commit.
+        ls dist/*-"${GITHUB_REF_NAME#v}".tar.gz
+
+    - name: Upload to the package registry
+      env:
+        TWINE_REPOSITORY_URL: ${{ github.server_url }}/api/packages/${{ github.repository_owner }}/pypi
+        TWINE_USERNAME: ${{ github.repository_owner }}
+        # The job's own token can read packages but not write them, so this
+        # is an access token with package write permission, stored as an
+        # Actions secret (owner-level, inherited by every repository).
+        TWINE_PASSWORD: ${{ secrets.PUBLISH_TOKEN }}
+      run: |
+        if [ -z "${TWINE_PASSWORD:-}" ]; then
+          echo "::error::PUBLISH_TOKEN secret is not set; nothing was uploaded."
+          exit 1
+        fi
+        twine upload dist/*
+
+  publish-package:
+    runs-on: ubuntu-latest
+    needs: [test, lint, package, security-scan]
+    # Publishes to PyPI with the PYPI_API_TOKEN repository secret, which
+    # exists only on GitHub: a release cut on a self-hosted server must not
+    # try to upload (publish-registry serves that side). Version tags only:
+    # a release under any other tag would upload a distribution whose
+    # setuptools_scm version came from a tag that is not one.
+    if: github.event_name == 'release' && github.event.action == 'published' && startsWith(github.event.release.tag_name, 'v') && github.server_url == 'https://github.com'
+
+    steps:
+    - uses: actions/checkout@v7
+      with:
+        fetch-depth: 0   # setuptools_scm derives the version from tags
+
+    - name: Set up Python
+      uses: actions/setup-python@v7
+      with:
+        python-version: '3.11'
+
+    - name: Install build dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install build twine
+
+    - name: Build package
+      run: python -m build
+
+    - name: Check package
+      run: twine check dist/*
+
+    - name: Publish to PyPI
+      env:
+        TWINE_USERNAME: __token__
+        TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+      run: twine upload dist/*

talkpipe_agents-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+.pytest_cache/
+build/
+dist/
+.coverage
+coverage.xml
+htmlcov/
+.mypy_cache/
+bandit-report.json
+safety-report.json
+.ruff_cache/

talkpipe_agents-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,20 @@
+# Opt-in desktop hooks mirroring the CI lint job: `pre-commit install` once
+# per clone; `pre-commit run --all-files` reproduces the gate locally.
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.17.0  # keep in step with the ruff pin in pyproject.toml
+    hooks:
+      - id: ruff-check
+        args: [--fix, --show-fixes]
+      - id: ruff-format
+  - repo: local
+    hooks:
+      - id: mypy
+        name: mypy
+        # The project venv's mypy (so versions match uv.lock): install and
+        # run pre-commit from inside it -- `uv run pre-commit ...` or an
+        # activated .venv -- so `mypy` resolves on PATH.
+        entry: mypy
+        language: system
+        types: [python]
+        pass_filenames: false

talkpipe_agents-0.1.0/.safety-policy.yml

@@ -0,0 +1,58 @@
+version: '3.0'
+
+scanning-settings:
+  max-depth: 6
+  exclude: []
+  include-files: []
+  system:
+    targets: []
+
+
+report:
+  dependency-vulnerabilities:
+    enabled: true
+    auto-ignore-in-report:
+      python:
+        # Both are deliberately false: findings against the installed
+        # environment and against unpinned declared requirements must show up
+        # in the report and fail the scan. Do not flip these back to true to
+        # get a red build green -- fix the requirement instead.
+        environment-results: false
+        unpinned-requirements: false
+      cvss-severity: []
+
+
+fail-scan-with-exit-code:
+  dependency-vulnerabilities:
+    enabled: true
+    fail-on-any-of:
+      cvss-severity:
+        - high
+        - medium
+        - critical
+      exploitability:
+        - high
+        - medium
+        - critical
+
+security-updates:
+  dependency-vulnerabilities:
+    auto-security-updates-limit:
+      - patch
+
+installation:
+  default-action: allow
+  audit-logging:
+    enabled: true
+  allow:
+    packages: []
+    vulnerabilities: {}
+  deny:
+    packages: {}
+    vulnerabilities:
+      warning-on-any-of:
+        cvss-severity: []
+      block-on-any-of:
+        cvss-severity: []
+
+