Skip to content

fix: YNAB API 1.86 parity (Milestone 0) + eval dry-run intent capture - #18

Open
klauern wants to merge 11 commits into
mainfrom
codex/ynab-api-parity-backlog
Open

fix: YNAB API 1.86 parity (Milestone 0) + eval dry-run intent capture#18
klauern wants to merge 11 commits into
mainfrom
codex/ynab-api-parity-backlog

Conversation

@klauern

@klauern klauern commented Aug 8, 2026

Copy link
Copy Markdown
Owner

What changed

Closes all five Milestone-0 parity issues plus the eval dry-run capture work, leaving a clean baseline:

YNAB API 1.86 parity (P0)

  • SDK 4.3 lock (mcp-ynab-parity-sdk): ynab>=4.3.0,<5; contract tests pin until_date on all transaction-list methods, goal_frequency modeling, and HTTP 200 SaveTransactionsResponse decoding (4.1.0 still expected 209).
  • All 13 account types (mcp-ynab-parity-account-types): cash / lineOfCredit / personalLoan / medicalDebt / otherDebt were silently dropped from display and totals. Unknown future types now stay visible instead of vanishing; summary signs fixed ($-500-$500).
  • Category lookup ownership (mcp-ynab-parity-category-read): get_transactions_by_category called a method that only exists on TransactionsApi via CategoriesApi — guaranteed AttributeError on a real SDK. Permissive MagicMock tests were hiding it.
  • Explicit unbounded semantics (mcp-ynab-parity-unbounded): merge_payees, days_back=None attention reads, reconciliation/subset "defaults to all" reads, and alternate-ID scans now pass an explicit all-history bound (1970-01-01) instead of YNAB's implicit one-year since_date truncation; user-visible ranges are reported.
  • Scheduled date validation (mcp-ynab-parity-scheduled-dates): start date must be strictly future and ≤ 5 years out (UTC); today/past/over-limit fail locally before any API call; default is tomorrow UTC.

Eval harness (g57.8 + g57.5/g57.6 partial)

  • Server-side dry-run intent recorder: MCP_YNAB_EVAL_DRY_RUN_INTENTS_PATH intercepts every mutating handler and persists validated payloads to intended_writes.json (no env var → production unchanged).
  • Deterministic grading.json per task/config, viewer-compatible benchmark.json + token-delta-first benchmark.md, richer evals.json assertions, README docs.

Verification

  • 373 tests pass (20 integration/LLM deselected), ruff format + check clean.
  • New tests: SDK contracts (4), account-type classification (3), category ownership (4), unbounded-range regressions (5), scheduled-date boundaries (3).

Beads

Milestone-0 epic and its five children closed; g57.8 closed. g57.5/g57.6/g57.7 remain tracked with progress notes.

Summary by CodeRabbit

  • New Features

    • Added optional dry-run support for write actions, recording intended changes without applying them.
    • Added comprehensive benchmark and grading reports for evaluation runs.
    • Expanded account summaries to support all official account types and unknown future types.
  • Bug Fixes

    • Improved all-history transaction, payee, and reconciliation searches.
    • Improved category transaction lookups and alternate-ID handling.
    • Scheduled transactions now default to tomorrow and require valid future dates.
  • Documentation

    • Updated evaluation guidance with benchmark commands, grading details, metrics, and reports.

klauern added 8 commits August 6, 2026 20:14
…ark report

Implements g57.8 (simulated mutation-intent capture) and completes the
reporting half of g57.5/g57.6:

- server: MCP_YNAB_EVAL_DRY_RUN_INTENTS_PATH opt-in intercepts every
  mutating handler (except the Code Mode dispatcher) and persists the
  validated payload to intended_writes.json instead of dispatching.
  No env var => production behavior unchanged.
- dual runner: per-surface intent artifacts seeded before each run,
  grading.json written for every task/config after runs finish.
- grading: deterministic assertions (completion, write-safety, expected
  read ops, task-specific text expectations, intended-write payload shape).
- benchmark: viewer-compatible benchmark.json + token-delta-first
  benchmark.md at the iteration root.
- evals.json: adds intent_expectation + text expectations to all tasks.
- README documents the dry-run recorder and benchmark workflow.
Raise the dependency floor to ynab>=4.3.0,<5 and refresh uv.lock. Pins
OpenAPI 1.86 contracts with focused tests:

- until_date exists on all five transaction-list methods
- goal_frequency is modeled on NewCategory (monthly/weekly/yearly)
- update_transactions decodes an HTTP 200 SaveTransactionsResponse
  (4.1.0 mapped bulk-write success to 209, which the live API no longer
  returns)
- get_transactions_by_category is owned by TransactionsApi, and the
  permissive CategoriesApi mock route is removed
…cp-ynab-parity-account-types)

The account formatter iterated only 8 of 13 AccountType values, silently
dropping cash, lineOfCredit, personalLoan, medicalDebt and otherDebt
accounts from display and totals.

- add the five missing types with display names and correct
  asset/liability classification (cash is an asset; the rest are
  liabilities)
- keep unknown future account types visible in their own group instead
  of dropping them; unknown types are never miscounted into totals
- use _format_dollar_amount for summary signs (fixes $-500.00 output)
- tests cover all 13 enum values, asset/liability totals, and unknown-type
  visibility
…p (mcp-ynab-parity-category-read)

get_transactions_by_category constructed CategoriesApi and called
get_transactions_by_category on it, but that method exists only on
TransactionsApi — a guaranteed AttributeError against a real SDK.
Permissive MagicMock tests invented the missing method and hid the bug.

- call TransactionsApi.get_transactions_by_category instead
- update unit tests to mock the TransactionsApi route
- add a real-SDK ownership assertion: TransactionsApi has the method,
  CategoriesApi does not
…r default (mcp-ynab-parity-unbounded)

API 1.85 defaults an omitted since_date to one year ago. merge_payees,
attention queries with days_back=None, "defaults to all" reconciliation
reads, and alternate-ID scans all relied on that implicit truncation and
could silently miss transactions older than one year.

- add date_bounds.ALL_HISTORY_SINCE_DATE (1970-01-01) as the explicit
  all-history bound
- merge_payees: pass the bound and report the scanned range in its output
- get_transactions_needing_attention: days_back=None now fetches all
  history and reports the range
- get_account_reconciliation_profile / subset-matches: since_date=None
  now means an explicit all-history bound
- alternate-ID resolution: transfer/matched ids scan all history instead
  of YNAB's default; unparseable import_id dates fall back to the bound
- regression tests cover every site, including pre-one-year fixtures
…parity-scheduled-dates)

The official API requires a scheduled transaction start date strictly in
the future and no more than five years out. create_scheduled_transaction
defaulted to local today and passed any value straight to the SDK.

- default start date is tomorrow in UTC (strictly future)
- today and past dates fail locally with a clear ValueError
- dates more than five calendar years out fail locally (Feb 29 handled)
- the exact five-year limit is accepted
- nothing invalid ever reaches the API (no HTTP 400 round-trip)
- tests cover UTC reference frame, today/past rejection, the five-year
  boundary, and over-limit rejection
…6 progress

Closed: mcp-ynab-parity-sdk, -account-types, -category-read, -unbounded,
-scheduled-dates, the Milestone-0 epic, and g57.8 (dry-run intent capture,
forced past the orthogonal g57.7 read-snapshot dependency).
@github-actions github-actions Bot added the patch Release: patch version bump label Aug 8, 2026
@coderabbitai

coderabbitai Bot commented Aug 8, 2026

Copy link
Copy Markdown

Review Change Stack

Warning

Review limit reached

@klauern, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 56 minutes

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 9cac83cf-8945-4dfd-8fa1-78649d8c3fd7

📥 Commits

Reviewing files that changed from the base of the PR and between 79ecb57 and 5e8eba3.

📒 Files selected for processing (12)
  • evals/aggregate_benchmark.py
  • evals/evals.json
  • evals/grading.py
  • src/mcp_ynab/dry_run.py
  • src/mcp_ynab/formatters.py
  • src/mcp_ynab/tools/code_mode.py
  • src/mcp_ynab/tools/transactions.py
  • tests/integration/_llm_eval_harness.py
  • tests/test_dry_run.py
  • tests/test_dual_eval_runner.py
  • tests/test_llm_eval_harness.py
  • tests/test_server.py
📝 Walkthrough

Walkthrough

This PR adds deterministic grading and benchmarking for Code Mode and direct-tool evaluations, records dry-run mutation intents, expands evaluation expectations, and corrects YNAB account, transaction-date, scheduled-transaction, category-lookup, and SDK handling.

Changes

YNAB API and transaction correctness

Layer / File(s) Summary
Transaction, account, and SDK correctness
pyproject.toml, src/mcp_ynab/date_bounds.py, src/mcp_ynab/formatters.py, src/mcp_ynab/tools/budgeting.py, src/mcp_ynab/tools/transactions.py, tests/test_server.py, tests/test_tools.py, tests/test_ynab_sdk_contracts.py
Adds explicit all-history bounds, official account classifications, scheduled-date validation, the TransactionsApi category endpoint, and SDK contract tests.

Dry-run mutation capture

Layer / File(s) Summary
Dry-run mutation interception
src/mcp_ynab/dry_run.py, src/mcp_ynab/server.py, src/mcp_ynab/tools/code_mode.py, tests/test_dry_run.py
Intercepts validated write calls, persists intent records, returns synthetic responses, and enables mutation discovery in dry-run Code Mode.

Evaluation grading and benchmarking

Layer / File(s) Summary
Deterministic grading and benchmark reports
evals/evals.json, evals/grading.py, evals/aggregate_benchmark.py, evals/run_dual_eval.py, evals/README.md, tests/integration/_llm_eval_harness.py, tests/test_dual_eval_runner.py, .beads/interactions.jsonl
Adds structured expectations, grading artifacts, intent-file wiring, benchmark JSON and Markdown reports, updated evaluation instructions, and supporting tests.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant EvalRunner
  participant MCPServer
  participant DryRunInterceptor
  participant Grader
  participant BenchmarkAggregator

  EvalRunner->>MCPServer: Launch Code Mode or direct-tool evaluation
  MCPServer->>DryRunInterceptor: Intercept validated mutation call
  DryRunInterceptor-->>EvalRunner: Persist intended_writes.json
  EvalRunner->>Grader: Grade run artifacts
  Grader-->>EvalRunner: Write grading.json
  EvalRunner->>BenchmarkAggregator: Aggregate configuration results
  BenchmarkAggregator-->>EvalRunner: Write benchmark.json and benchmark.md
Loading

Possibly related PRs

  • klauern/mcp-ynab#3: Both changes cover transaction categorization and tests/test_server.py.
  • klauern/mcp-ynab#7: Both changes modify Code Mode mutation handling and server integration.
  • klauern/mcp-ynab#12: This PR extends the evaluation framework with grading, intent capture, and benchmark aggregation.
🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 41.43% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title clearly summarizes the two primary changes: YNAB API parity fixes and evaluation dry-run intent capture.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch codex/ynab-api-parity-backlog

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 7

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)
tests/test_tools.py (1)

2193-2200: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Control the UTC date in scheduled transaction tests.

A UTC midnight can change the expected date during a test. February 29 also makes direct five-year construction invalid for a non-leap target year.

  • tests/test_tools.py#L2193-L2200: inject or freeze the UTC date before calling the tool.
  • tests/test_tools.py#L2224-L2245: derive the boundary with the same leap-day handling as production code.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@tests/test_tools.py` around lines 2193 - 2200, Control the UTC date in
tests/test_tools.py#L2193-L2200 by injecting or freezing the UTC clock before
invoking create_scheduled_transaction, then assert against that controlled date
plus one day. In tests/test_tools.py#L2224-L2245, derive the five-year boundary
using the same leap-day handling as the production date logic instead of
directly constructing an invalid non-leap-year February 29 date.
🧹 Nitpick comments (1)
src/mcp_ynab/tools/transactions.py (1)

40-40: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Use Python 3.12 union syntax.

Replace Optional[int] with int | None.

Proposed fix
-def _explicit_since_date(days_back: Optional[int]) -> date:
+def _explicit_since_date(days_back: int | None) -> date:
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/mcp_ynab/tools/transactions.py` at line 40, Update the
_explicit_since_date function signature to use Python 3.12 union syntax,
replacing Optional[int] with int | None while preserving the existing behavior.

Source: Coding guidelines

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@evals/aggregate_benchmark.py`:
- Line 20: Reformat the variance calculation in the aggregate benchmark logic so
no line exceeds 100 characters. Split the conditional expression across lines or
assign the denominator separately while preserving the existing sample-variance
behavior and 0.0 result for fewer than two values.

In `@evals/evals.json`:
- Around line 17-21: Update the regex expectations in evals/evals.json at lines
17-21, 72-76, 195-198, and 230-232: require currency-formatted amounts for
dining spending and cash balance, and use bounded patterns matching either
$50/50 dollars or $200/200 dollars for the respective checks, preventing
unrelated numbers or larger amounts from satisfying them.

In `@evals/run_dual_eval.py`:
- Around line 201-209: Update the Agent SDK execution path used by _run_config
and drive_prompt so server_env_overrides, including
MCP_YNAB_EVAL_DRY_RUN_INTENTS_PATH, is forwarded through _drive_via_agent_sdk;
alternatively, explicitly reject Agent SDK execution in this runner. Ensure
Agent SDK mutation runs cannot proceed without either the configured dry-run
intent artifact or a clear rejection.

In `@src/mcp_ynab/dry_run.py`:
- Around line 64-79: Update tests/test_dry_run.py (lines 22-85) to exercise the
intercepted tools through the real FastMCP call_tool() dispatch, covering both
valid arguments and invalid arguments to verify validation still runs. Adjust
src/mcp_ynab/dry_run.py (lines 64-79) only as needed so the replacement
performed by the interceptor remains compatible with FastMCP dispatch and
preserves argument validation.

In `@src/mcp_ynab/tools/code_mode.py`:
- Around line 39-46: Update the Code Mode mutation documentation near the
statements describing code_mode_mutations_enabled to note that dry-run mode is
an explicit exception: it permits ynab.write.* handlers even when that
preference is disabled. Keep the existing preference requirement documented for
normal operation.

In `@src/mcp_ynab/tools/transactions.py`:
- Around line 1203-1206: Update the docstring for the scheduled transaction tool
near _validate_scheduled_transaction_date to state that start_date defaults to
tomorrow in UTC, matching the fallback assigned to txn_date. Leave the
validation and date calculation unchanged.
- Around line 497-500: Update the days-back rendering condition in the
transaction markdown construction to check whether days_back is not None, so a
value of 0 renders as a zero-day lookback while None retains the all-history
message.

---

Outside diff comments:
In `@tests/test_tools.py`:
- Around line 2193-2200: Control the UTC date in tests/test_tools.py#L2193-L2200
by injecting or freezing the UTC clock before invoking
create_scheduled_transaction, then assert against that controlled date plus one
day. In tests/test_tools.py#L2224-L2245, derive the five-year boundary using the
same leap-day handling as the production date logic instead of directly
constructing an invalid non-leap-year February 29 date.

---

Nitpick comments:
In `@src/mcp_ynab/tools/transactions.py`:
- Line 40: Update the _explicit_since_date function signature to use Python 3.12
union syntax, replacing Optional[int] with int | None while preserving the
existing behavior.
🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: c50a82f4-29ab-41cb-ab99-f415c87bde3f

📥 Commits

Reviewing files that changed from the base of the PR and between 2dc38b8 and 79ecb57.

⛔ Files ignored due to path filters (1)
  • uv.lock is excluded by !**/*.lock
📒 Files selected for processing (21)
  • .beads/interactions.jsonl
  • .beads/issues.jsonl
  • evals/README.md
  • evals/aggregate_benchmark.py
  • evals/evals.json
  • evals/grading.py
  • evals/run_dual_eval.py
  • pyproject.toml
  • src/mcp_ynab/date_bounds.py
  • src/mcp_ynab/dry_run.py
  • src/mcp_ynab/formatters.py
  • src/mcp_ynab/server.py
  • src/mcp_ynab/tools/budgeting.py
  • src/mcp_ynab/tools/code_mode.py
  • src/mcp_ynab/tools/transactions.py
  • tests/integration/_llm_eval_harness.py
  • tests/test_dry_run.py
  • tests/test_dual_eval_runner.py
  • tests/test_server.py
  • tests/test_tools.py
  • tests/test_ynab_sdk_contracts.py

Comment thread evals/aggregate_benchmark.py Outdated
Comment thread evals/evals.json Outdated
Comment thread evals/run_dual_eval.py
Comment thread src/mcp_ynab/dry_run.py
Comment thread src/mcp_ynab/tools/code_mode.py
Comment thread src/mcp_ynab/tools/transactions.py Outdated
Comment thread src/mcp_ynab/tools/transactions.py

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 79ecb57d63

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread evals/run_dual_eval.py
Comment thread src/mcp_ynab/dry_run.py
Comment thread evals/grading.py
Comment thread src/mcp_ynab/formatters.py Outdated
Comment on lines +165 to +168
if acct_type in asset_types:
output["summary"]["total_assets"] += group_total
elif acct_type in liability_types:
output["summary"]["total_liabilities"] += abs(group_total)

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Keep positive liability balances positive in net worth

When a liability-type account has a positive balance, such as an overpaid credit card or line of credit, applying abs() treats that credit as debt and then subtracts it from net worth. For example, a lone lineOfCredit balance of +$100 is reported as $100 of liabilities and -$100 net worth instead of contributing +$100. Compute net worth from signed account balances and count only outstanding negative liability balances as liabilities.

Useful? React with 👍 / 👎.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

patch Release: patch version bump

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant