[MehdiZare]

Fractional share totals in successful insider-statistics responses currently raise Pydantic validation errors. A fractional historical row can therefore prevent either sync or async client from returning a valid first row.

Change total_acquired and total_disposed to float in both InsiderStatistic and InsiderTradingStatistics, preserving the reported quantities without explicit rounding. Transaction counts remain integers, aliases and validation stay intact, and both public methods keep returning the first validated row. Update the integration type assertions and Unreleased changelog.

Closes #395

Verification (Python 3.12.12, Pydantic 2.13.5, uv 0.12.13):

• New regression module before the fix: 26 failed, 12 passed. Failures include the reported int_from_float errors and sync/async multirow response processing.
• .venv/bin/pytest tests/unit/test_insider_statistics_fractional.py tests/unit/test_institutional.py tests/unit/test_async_clients.py: 319 passed, including all 38 new regressions. Covers both issue-provided NVDA rows, MSFT/AVGO fractional quantities, whole/zero totals, JSON aliases, integer counts, retained historical rows, and rejection of malformed historical rows.
• CI=true make ci: all 7 nox sessions passed (lint, full typing, security audit, core coverage, extras coverage, import smoke, and aggregator). Combined core coverage 92.24%; extras coverage 88.15%. Core runs: 2,585 passed / 300 skipped / 8 deselected each; MCP run: 286 passed / 9 skipped; extras run: 3,090 passed / 9 skipped.
• Ruff lint/format checks and mypy on all three touched Python files passed. Full pre-commit checks passed.
• FMP_VCR_RECORD=none .venv/bin/pytest tests/integration/test_institutional.py: 31 skipped because replay cassettes are unavailable. No live-provider acceptance is claimed.

The initial parallel make ci run hit the existing test_a_second_plain_handler_sees_masked_extras test-order problem (empty INFO log after an earlier fixture configures ERROR). Reproduced on an archive of unchanged dev 75c7592 by running tests/unit/test_institutional.py followed by that logger test: 49 passed, 1 failed. The logger test passes in isolation. No logger changes are included.

Package publication and downstream upgrade remain release follow-up work. This PR targets dev; it does not publish a release.

Summary by CodeRabbit

• New Features

  • Insider statistics now preserve fractional share totals for acquired and disposed quantities.
  • Fractional values are supported in both synchronous and asynchronous data retrieval.

• Bug Fixes

  • Improved processing of historical insider-statistics data containing fractional quantities.
  • Transaction counts continue to be validated as whole numbers.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: 63d1d74e-b206-4fed-86c1-3d1c878edd95

📥 Commits

Reviewing files that changed from the base of the PR and between 75c7592 and da68122.

📒 Files selected for processing (4)

• CHANGELOG.md
• fmp_data/institutional/models.py
• tests/integration/test_institutional.py
• tests/unit/test_insider_statistics_fractional.py

Included review availability: 0 reviews are currently available. Your included PR review attempts over the past 7 days set your current allowance at 1 review per hour.

---

Walkthrough

The change updates both insider-statistics models to preserve fractional share totals. It adds synchronous and asynchronous regression coverage for multirow responses, validation, serialization, and invalid fractional transaction counts.

Changes

Insider-statistics fractional totals

Layer / File(s)	Summary
Fractional total fields fmp_data/institutional/models.py, CHANGELOG.md	total_acquired and total_disposed now use float values in both insider-statistics models. Field descriptions and the changelog state that totals include fractional shares.
Parsing and validation coverage tests/unit/test_insider_statistics_fractional.py, tests/integration/test_institutional.py	Tests cover fractional totals, integer transaction counts, multirow response processing, synchronous and asynchronous clients, serialization, and validation errors for invalid totalDisposed values.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Bug fix · Severity of issue fixed: Medium

Merge Risk: ⚪ Minimal · up to da681

Fractional insider-share totals are supported across both models and client paths while transaction counts remain integer-validated. The change is ready to merge.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 11.11% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 9 functions across 3 files. (1 skipped: 1…	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 and concisely describes the main change: accepting fractional insider share totals in institutional models.
Linked Issues check	✅ Passed	The PR meets the coding requirements in #395. InsiderStatistic and InsiderTradingStatistics declare total_acquired and total_disposed as float, so fractional values remain available without …
Out of Scope Changes check	✅ Passed	The changes stay within #395. Model declarations implement the fix. Unit tests and integration type assertions verify the required behavior. The changelog documents the consumer-facing change. No unre…

Full details: Docstring Coverage

Explanation

Docstring coverage is 11.11% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 9 functions across 3 files. (1 skipped: 1 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/395-fractional-insider-totals

---

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

[MehdiZare]

Quoting #399 (comment)

No action — the walkthrough matches the diff; there are no line-level findings.

The docstring-coverage warning is declined: the touched functions are parameterized regressions, and the model fields already carry Field descriptions at fmp_data/institutional/models.py:253 and :541. Adding test-function docstrings would not change consumer-visible behavior or the #395 contract (fractional total_acquired / total_disposed as float, integer transaction counts). CodeRabbit’s check is not a required GitHub gate.