yadirect-agent 0.1.0__tar.gz

yadirect_agent-0.1.0/.env.example

@@ -0,0 +1,49 @@
+# =========================================================
+# Yandex Direct Agent — configuration
+# Copy to .env and fill in. NEVER commit .env.
+# =========================================================
+
+# --- Yandex auth (OAuth) ---
+# Register an app at https://oauth.yandex.ru/ with scopes:
+#   direct:api, metrika:read, metrika:write
+# Use scripts/get_oauth_token.py to obtain a token.
+YANDEX_DIRECT_TOKEN=
+YANDEX_METRIKA_TOKEN=
+
+# Numeric counter ID for the website attached to this Direct account.
+# Required for the M6 reporting service (campaign_performance,
+# account_overview, conversion_by_source). Find it in the Metrika UI
+# at the top of the counter's dashboard, or via list_counters.
+YANDEX_METRIKA_COUNTER_ID=
+
+# M15.5 health check — account-wide target CPA in RUB. The high-CPA
+# rule uses this to flag campaigns spending above the acceptable cost
+# per conversion. Leave empty to disable that rule for now.
+ACCOUNT_TARGET_CPA_RUB=
+
+# For agency accounts: login of the client sub-account to act on.
+# Leave empty for direct accounts.
+YANDEX_CLIENT_LOGIN=
+
+# Safety: start in sandbox. Flip to false only after you've verified things.
+YANDEX_USE_SANDBOX=true
+
+# --- Anthropic ---
+ANTHROPIC_API_KEY=
+# Always use the latest Opus for the agent loop; costs a bit more but
+# multi-step planning quality makes it pay off vs Sonnet for ads.
+ANTHROPIC_MODEL=claude-opus-4-7
+
+# --- Agent behaviour ---
+# Which operations auto-approve vs require human confirmation.
+# See agent/safety.py for the policy schema.
+AGENT_POLICY_PATH=./agent_policy.yml
+
+# Hard daily spend guard. If total budget across managed campaigns
+# exceeds this (RUB), the agent refuses further changes.
+AGENT_MAX_DAILY_BUDGET_RUB=10000
+
+# --- Observability ---
+LOG_LEVEL=INFO
+LOG_FORMAT=json                     # json | console
+AUDIT_LOG_PATH=./logs/audit.jsonl

yadirect_agent-0.1.0/.github/ISSUE_TEMPLATE/bug.yml

@@ -0,0 +1,70 @@
+name: Bug report
+description: Something is broken in yadirect-agent.
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting. Please fill in the fields below so we can reproduce.
+
+  - type: input
+    id: version
+    attributes:
+      label: Version
+      description: Output of `python -c "import yadirect_agent; print(yadirect_agent.__version__)"`
+      placeholder: "0.1.0"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: mode
+    attributes:
+      label: Mode
+      options:
+        - CLI agent
+        - MCP server
+        - Library / programmatic
+        - Tests / dev tooling
+    validations:
+      required: true
+
+  - type: dropdown
+    id: environment
+    attributes:
+      label: Yandex environment
+      options:
+        - sandbox
+        - production
+    validations:
+      required: true
+
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: What did you do, what did you expect, what happened instead?
+      placeholder: |
+        Steps:
+        1.
+        2.
+        Expected:
+        Actual:
+    validations:
+      required: true
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant logs
+      description: |
+        Include structured log lines (one JSON per line). **Redact any tokens
+        or personally identifiable data before pasting.**
+      render: shell
+
+  - type: checkboxes
+    id: safety
+    attributes:
+      label: Confirm
+      options:
+        - label: I have removed tokens, OAuth codes, and account identifiers from pasted output.
+          required: true

yadirect_agent-0.1.0/.github/ISSUE_TEMPLATE/feature.yml

@@ -0,0 +1,32 @@
+name: Feature request
+description: Propose new functionality or an improvement.
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What real task or pain is this solving? Link to the milestone in `docs/TECHNICAL_SPEC.md` if one fits.
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposal
+      description: Sketch the API / CLI / tool surface. Rough is fine — we'll iterate.
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: What have you already ruled out, and why?
+
+  - type: textarea
+    id: safety
+    attributes:
+      label: Safety implications
+      description: |
+        Does this expand the set of mutating operations, touch bidding,
+        budgets, or audience settings? If yes — how do we keep it reversible
+        and policy-gated?

yadirect_agent-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,49 @@
+<!--
+Thanks for opening a PR. Every box in "Reviewer checklist" corresponds to an
+item in docs/REVIEW.md — please self-check before requesting review.
+-->
+
+## What & why
+
+<!-- One-paragraph summary. Link the milestone / issue. -->
+
+Closes: #
+
+## How
+
+<!--
+Call out:
+- new modules / responsibilities
+- any changes to the safety surface (policy schema, kill-switches, audit)
+- any blocking I/O introduced (should be none)
+-->
+
+## Tests
+
+- [ ] **TDD trail is visible**: at least one `test:` commit precedes the
+      matching `feat:`/`fix:` commit for every new behaviour. Exempt PR
+      types: `refactor`, `docs`, `chore`, `ci`, `build`, `style`. If this
+      PR bundles a feature into a single commit, the commit body states
+      "tests written first". See `docs/TESTING.md#tdd_workflow`.
+- [ ] Unit tests added / updated (`pytest -q` green locally)
+- [ ] `respx` fixtures cover the happy and failure paths for new HTTP calls
+- [ ] Coverage for changed files ≥ 80%
+
+## Checklist (see `docs/REVIEW.md`)
+
+- [ ] `make check` passes (`lint + type + test`)
+- [ ] No business logic in `clients/` — only HTTP + type mapping
+- [ ] No blocking calls in the async main path
+- [ ] No secrets logged or committed
+- [ ] Error paths use typed exceptions from `exceptions.py`
+- [ ] Destructive / mutating changes go through the plan → confirm → execute flow
+- [ ] Public API / flags documented in `README.md` and the relevant doc in `docs/`
+
+## Safety notes
+
+<!--
+If this PR adds mutating capability:
+- Which kill-switches apply?
+- Is the default `agent_policy.yml` sane out of the box?
+- Is the operation reversible? If not, say so explicitly.
+-->

yadirect_agent-0.1.0/.github/dependabot.yml

@@ -0,0 +1,59 @@
+# Dependabot configuration.
+#
+# Rationale: the agent links user money to a third-party advertising API
+# through a small-but-growing dependency graph. A malicious or
+# accidentally broken update — in httpx, anthropic, tenacity — would
+# land on main silently if we relied on manual bumps.
+#
+# Strategy:
+# - Weekly cadence (lower review cost than daily for a solo project).
+# - Grouped minor / patch updates to reduce noise — one PR per week per
+#   ecosystem when there's anything to bump.
+# - Labels so the PRs are filterable and the review tier is obvious.
+# - Security updates are NOT grouped and run on Dependabot's own
+#   schedule regardless of the weekly cadence.
+version: 2
+updates:
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+      time: "06:00"
+      timezone: Europe/Moscow
+    groups:
+      minor-and-patch:
+        applies-to: version-updates
+        update-types:
+          - minor
+          - patch
+    labels:
+      - dependencies
+      - python
+    commit-message:
+      prefix: chore
+      prefix-development: chore
+      include: scope
+    open-pull-requests-limit: 5
+
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+      time: "06:00"
+      timezone: Europe/Moscow
+    groups:
+      all-actions:
+        applies-to: version-updates
+        update-types:
+          - minor
+          - patch
+          - major
+    labels:
+      - dependencies
+      - github-actions
+    commit-message:
+      prefix: ci
+      include: scope
+    open-pull-requests-limit: 3

yadirect_agent-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,56 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  check:
+    name: lint + type + test (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Ruff (lint + format check)
+        run: |
+          ruff check .
+          ruff format --check .
+
+      - name: mypy (strict)
+        run: mypy src/
+
+      - name: pytest (with coverage gate)
+        run: |
+          pytest -q \
+            --cov=src/yadirect_agent \
+            --cov-report=term-missing \
+            --cov-report=xml \
+            --cov-fail-under=80
+
+      - name: Upload coverage XML
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: coverage-${{ matrix.python-version }}
+          path: coverage.xml
+          if-no-files-found: ignore
+          retention-days: 7

yadirect_agent-0.1.0/.github/workflows/codeql.yml

@@ -0,0 +1,57 @@
+# CodeQL — GitHub-native static analysis for Python.
+#
+# Rationale: catches common security-relevant patterns (unsanitised
+# shell, unsafe deserialisation, missing auth checks, SQL injection,
+# etc.) on every push. It's a low-signal security net; most of our
+# real safety lives in the policy layer, but CodeQL catches the kind
+# of mistakes that slip through review.
+#
+# Cadence: on push to main, on PR to main, and weekly on Monday so a
+# new CodeQL rule set applied by GitHub isn't missed.
+
+name: CodeQL
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    # Monday 07:00 Europe/Moscow = 04:00 UTC.
+    - cron: "0 4 * * 1"
+
+permissions:
+  contents: read
+  security-events: write
+  actions: read
+
+jobs:
+  analyze:
+    name: Analyze (${{ matrix.language }})
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      matrix:
+        language: [python]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v4
+        with:
+          languages: ${{ matrix.language }}
+          # 'security-and-quality' is the broader pack; it catches more
+          # maintainability issues in addition to pure security bugs.
+          # If noise becomes a problem, drop to 'security-extended'.
+          queries: security-and-quality
+
+      - name: Autobuild
+        uses: github/codeql-action/autobuild@v4
+
+      - name: Perform CodeQL analysis
+        uses: github/codeql-action/analyze@v4
+        with:
+          category: "/language:${{ matrix.language }}"

yadirect_agent-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,151 @@
+name: Release
+
+# Triggered when a tag matching v*.*.* is pushed (e.g. v0.1.0).
+# Builds sdist + wheel and publishes to PyPI via Trusted Publishing
+# (OIDC) — no PyPI token stored anywhere in this repo.
+#
+# One-time prerequisite: register this workflow as a Trusted
+# Publisher at pypi.org → "Manage" → "Publishing":
+#   PyPI Project Name:   yadirect-agent
+#   Owner:               Kozharina
+#   Repository name:     yadirect-agent
+#   Workflow name:       release.yml
+#   Environment name:    pypi
+# Until that registration exists, the publish step will fail with
+# a clear "Trusted Publisher not configured" error and the build
+# artefacts remain available on the workflow run for inspection.
+#
+# To cut a release:
+#   1. Bump version in pyproject.toml on main
+#   2. git tag v<version> && git push origin v<version>
+#   3. This workflow runs, builds, publishes, attaches artefacts
+#      to a GitHub release.
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+# Concurrency lock per tag. ``cancel-in-progress: false`` is
+# deliberate (auditor M15.1 LOW-3): on a duplicate tag push, run
+# #1 publishes to PyPI; run #2 then attempts the same upload and
+# PyPI rejects it with "File already exists" because filenames
+# are deterministic. Workflow run #2 ends red with a clear error,
+# no double-publish, no orphaned half-state. Cancelling run #1
+# mid-flight (the alternative) could leave a PyPI release with
+# no matching GitHub release if cancellation lands between the
+# two upload steps.
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  # Stage 1: build the package on a clean runner. Output the
+  # artefacts so the publish job can pick them up. The build is
+  # deliberately minimal — no tests here; tests run on every PR
+  # via ci.yml. A tag must come from main, which means tests
+  # already passed.
+  #
+  # Repository guard: a fork that pushes a v*.*.* tag would also
+  # trigger this workflow. We refuse to do anything on a fork —
+  # PyPI's Trusted Publisher would reject the OIDC claim anyway,
+  # but consuming the fork's Actions minutes / artefact storage
+  # / running ``python -m build`` against potentially malicious
+  # ``pyproject.toml`` build hooks is also pointless.
+  # (auditor M15.1 MEDIUM-3.)
+  build:
+    if: github.repository == 'Kozharina/yadirect-agent'
+    name: Build sdist and wheel
+    runs-on: ubuntu-latest
+    steps:
+      # Actions pinned to commit SHA (auditor M15.1 MEDIUM-1) so a
+      # malicious tag-move on a third-party action cannot substitute
+      # arbitrary code into the release pipeline. Dependabot's
+      # github-actions group will open PRs to advance these.
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+        with:
+          python-version: "3.11"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Verify tag matches pyproject version
+        run: |
+          # Tag is refs/tags/vX.Y.Z; strip the leading 'v'.
+          # Using $GITHUB_REF (env var, expanded by bash) rather than
+          # ${{ github.ref }} (template, substituted by GitHub Actions
+          # before the shell sees the script) keeps this safe against
+          # tag names containing shell metacharacters.
+          tag_version="${GITHUB_REF#refs/tags/v}"
+          if ! [[ "$tag_version" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            echo "::error::tag format invalid: $tag_version"
+            exit 1
+          fi
+          py_version=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          echo "Tag version: $tag_version"
+          echo "pyproject.toml version: $py_version"
+          if [ "$tag_version" != "$py_version" ]; then
+            echo "::error::tag $tag_version does not match pyproject.toml version $py_version"
+            exit 1
+          fi
+
+      - name: Install build tooling
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: List built artefacts
+        run: ls -lah dist/
+
+      - name: Upload build artefacts
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+          retention-days: 7
+
+  # Stage 2: publish to PyPI via Trusted Publishing. This job has
+  # ``id-token: write`` to mint the OIDC token, ``contents: write``
+  # to attach the artefacts to a GitHub release.
+  publish:
+    if: github.repository == 'Kozharina/yadirect-agent'
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/yadirect-agent
+    permissions:
+      id-token: write
+      contents: write
+
+    steps:
+      - name: Download build artefacts
+        uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6
+        with:
+          name: dist
+          path: dist/
+
+      # The action handles OIDC token minting and twine upload
+      # against the configured Trusted Publisher. No PYPI_TOKEN
+      # secret is read.
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # release/v1
+        with:
+          packages-dir: dist/
+
+      - name: Create GitHub release with artefacts
+        uses: softprops/action-gh-release@b4309332981a82ec1c5618f44dd2e27cc8bfbfda # v3
+        with:
+          files: dist/*
+          generate_release_notes: true
+          fail_on_unmatched_files: true

yadirect_agent-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+.env
+.env.local
+*.pyc
+__pycache__/
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+htmlcov/
+dist/
+build/
+*.egg-info/
+logs/
+.vcr_cassettes/
+agent_policy.local.yml

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

@@ -0,0 +1,52 @@
+# pre-commit hooks for yadirect-agent.
+#
+# Install locally with:  make install-hooks
+# CI also runs the same ruff rules via `make lint`, so hooks are belt-and-braces.
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-added-large-files
+        args: ["--maxkb=500"]
+      - id: detect-private-key
+      - id: check-merge-conflict
+      - id: mixed-line-ending
+        args: ["--fix=lf"]
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    # Pinned exact to match the ruff pin in pyproject.toml dev extras.
+    # Bumping ruff is a 3-file operation: here, pyproject.toml dev deps,
+    # and (if the new ruff ships new default lints) the code that trips
+    # them. See docs/TESTING.md on the version-skew lesson.
+    rev: v0.15.11
+    hooks:
+      - id: ruff
+        args: ["--fix", "--exit-non-zero-on-fix"]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.13.0
+    hooks:
+      - id: mypy
+        files: ^src/
+        # mypy runs in its own isolated venv here — every runtime dep whose
+        # types we rely on must be listed, otherwise we see false
+        # "module not found" errors that the in-venv mypy does not.
+        additional_dependencies:
+          - pydantic>=2.8
+          - pydantic-settings>=2.4
+          - httpx>=0.27
+          - structlog>=24.4
+          - tenacity>=9.0
+          - anthropic>=0.39
+          - typer>=0.12
+          - pyyaml>=6.0
+          - mcp>=1.0
+          - types-python-slugify
+          - types-pyyaml
+        args: ["--config-file=pyproject.toml"]