docs: Mais Retorno Free quota limits in resolver cascade - #44
Conversation
Make the optional resolver cascade step explicit about operator-owned API keys and the public Free tier (500 credits/month), so deploy wiring does not treat it as unlimited. Co-authored-by: Cursor <cursoragent@cursor.com>
Correct variable per-call credit costs and separate REST API-key wiring from MCP OAuth so the cascade docs do not imply one credit per resolution or the wrong auth path. Co-authored-by: Cursor <cursoragent@cursor.com>
📝 WalkthroughWalkthroughThe change documents Mais Retorno as an optional resolver source. It records REST API key and MCP OAuth authentication, shared Free-tier limits, rate-limit behavior, source classification, and the current integration status. ChangesMais Retorno resolver documentation
Estimated code review effort: 1 (Trivial) | ~5 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (1)
src/findata/resolver/engine.py (1)
10-13: 🔒 Security & Privacy | 🔵 Trivial | ⚡ Quick winUse deployment-side wording for provider ownership.
client-side / networkedis ambiguous and conflicts with the server-side REST provider described indocs/RESOLVER.md. It can suggest placing the REST API key in browser code. Useoutside the library / networked, and state that REST credentials remain in the operator's deployment. The provider documentation recommendsX-Api-Keyfor server-side REST and OAuth for MCP. (developers.maisretorno.com)🤖 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/findata/resolver/engine.py` around lines 10 - 13, Update the “External providers” documentation wording to say providers are outside the library and networked, not client-side/networked. Clarify that REST credentials remain in the operator’s deployment, while preserving the existing injected async callback and provider ownership guidance.Source: MCP tools
🤖 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 `@docs/RESOLVER.md`:
- Around line 131-132: Update the “Cota esgotada” entry in RESOLVER.md to state
that HTTP 429 ends when the billing cycle renews or when the operator upgrades
the plan, preserving the existing renewal behavior and email-warning detail.
- Around line 101-102: The resolver documentation and provider contract are
inconsistent: the resolver replaces AssetClassification with provider results
rather than merging fields or lowering confidence. Update docs/RESOLVER.md lines
101-102 and the corresponding contract description in
src/findata/resolver/engine.py lines 14-15 to state that providers control
overrides and confidence, and that cascade entries are carried forward from
enriched.cascade; do not describe merge or confidence-reduction behavior unless
implementing it in the resolver.
---
Nitpick comments:
In `@src/findata/resolver/engine.py`:
- Around line 10-13: Update the “External providers” documentation wording to
say providers are outside the library and networked, not client-side/networked.
Clarify that REST credentials remain in the operator’s deployment, while
preserving the existing injected async callback and provider ownership guidance.
🪄 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: f2077952-8d8b-487b-8e78-2a2bb6092225
📒 Files selected for processing (4)
CHANGELOG.mddocs/RESOLVER.mddocs/SOURCES_WITH_AUTH.mdsrc/findata/resolver/engine.py
| Cada degrau preenche o que o anterior não trouxe e **baixa a confidence**; | ||
| `source` reflete a origem final; `cascade` loga o caminho. Os degraus 2 a 4 são |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -eu
printf '%s\n' '--- candidate files ---'
git ls-files 'docs/RESOLVER.md' 'src/findata/resolver/engine.py' 'tests/*' | sed -n '1,120p'
printf '%s\n' '--- engine outline ---'
ast-grep outline src/findata/resolver/engine.py --view compact || true
printf '%s\n' '--- relevant documentation ---'
cat -n docs/RESOLVER.md | sed -n '80,125p'
printf '%s\n' '--- relevant engine section ---'
cat -n src/findata/resolver/engine.py | sed -n '1,180p'
printf '%s\n' '--- provider and confidence references ---'
rg -n -C 3 'confidence|cascade|source|provider|classification|classify' src/findata/resolver tests docs/RESOLVER.mdRepository: robertoecf/OpenFinData
Length of output: 50378
🏁 Script executed:
#!/bin/bash
set -eu
printf '%s\n' '--- resolver orchestration ---'
cat -n src/findata/resolver/engine.py | sed -n '640,740p'
printf '%s\n' '--- provider-focused tests ---'
cat -n tests/test_resolver.py | sed -n '285,340p'
printf '%s\n' '--- classification model ---'
cat -n src/findata/resolver/models.py | sed -n '145,180p'
printf '%s\n' '--- provider declarations and assignments ---'
rg -n -C 5 'AssetProvider|enriched|result = enriched|confidence|cascade|source' src/findata/resolver/engine.py tests/test_resolver.py
printf '%s\n' '--- static invariant verifier ---'
python3 - <<'PY'
from pathlib import Path
text = Path("src/findata/resolver/engine.py").read_text()
start = text.index(" for provider in providers or []:")
end = text.index(" return result", start)
loop = text[start:end]
checks = {
"provider receives current result": "await provider(norm, result)" in loop,
"provider result replaces current result": "result = enriched" in loop,
"cascade is explicitly combined": "enriched.cascade = [*result.cascade, *enriched.cascade]" in loop,
"confidence is explicitly reduced": any(
token in loop for token in (
"result.confidence -", "enriched.confidence -",
"confidence = min(", "confidence -= ", "confidence *= ",
)
),
}
for name, value in checks.items():
print(f"{name}: {value}")
print("--- loop ---")
print(loop)
PYRepository: robertoecf/OpenFinData
Length of output: 40636
Align the provider contract with the resolver behavior.
The resolver replaces the current AssetClassification with the provider result. It does not merge missing fields or reduce confidence; it only carries forward the returned enriched.cascade. Update both descriptions to document provider-controlled overrides, confidence, and cascade entries, or implement the documented merge behavior.
📍 Affects 2 files
docs/RESOLVER.md#L101-L102(this comment)src/findata/resolver/engine.py#L14-L15
🤖 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 `@docs/RESOLVER.md` around lines 101 - 102, The resolver documentation and
provider contract are inconsistent: the resolver replaces AssetClassification
with provider results rather than merging fields or lowering confidence. Update
docs/RESOLVER.md lines 101-102 and the corresponding contract description in
src/findata/resolver/engine.py lines 14-15 to state that providers control
overrides and confidence, and that cascade entries are carried forward from
enriched.cascade; do not describe merge or confidence-reduction behavior unless
implementing it in the resolver.
| | Rate limit | 15 req/s em todos os planos | | ||
| | Cota esgotada | HTTP 429 até renovar o ciclo (aviso por email ~80%) | |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
sed -n '90,145p' docs/RESOLVER.md
printf '\n--- external documentation ---\n'
curl -L --max-time 15 -sS https://developers.maisretorno.com/ | head -c 5000Repository: robertoecf/OpenFinData
Length of output: 7888
🌐 Web query:
site:developers.maisretorno.com HTTP 429 quota upgrade renewal Mais Retorno API
💡 Result:
If you receive an HTTP 429 Too Many Requests error when using the Mais Retorno API, it indicates that your current credit balance for the billing cycle has been exhausted [1]. To resolve this issue, you have two options: 1. Automatic Renewal: Your credit balance will automatically reset upon the start of your next monthly billing cycle [1]. 2. Immediate Upgrade: You can regain access immediately by upgrading your current API plan [1]. To manage your consumption and avoid hitting these limits, the official documentation recommends respecting the Cache-Control headers returned by the API [1]. Each endpoint has a defined max-age for caching; by utilizing this, you can significantly reduce the number of unnecessary requests, thereby conserving your credit balance [1]. For instance, endpoints such as /quotes/{identifier} and /asset-info/{identifier} have a cache duration of 90 minutes [1].
Citations:
Include the plan-upgrade path for exhausted quotas.
Document that HTTP 429 ends when the cycle renews or the operator upgrades the plan.
Proposed wording
-| Cota esgotada | HTTP 429 até renovar o ciclo (aviso por email ~80%) |
+| Cota esgotada | HTTP 429 até renovar o ciclo ou fazer upgrade (aviso por email ~80%) |📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| | Rate limit | 15 req/s em todos os planos | | |
| | Cota esgotada | HTTP 429 até renovar o ciclo (aviso por email ~80%) | | |
| | Rate limit | 15 req/s em todos os planos | | |
| | Cota esgotada | HTTP 429 até renovar o ciclo ou fazer upgrade (aviso por email ~80%) | |
🤖 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 `@docs/RESOLVER.md` around lines 131 - 132, Update the “Cota esgotada” entry in
RESOLVER.md to state that HTTP 429 ends when the billing cycle renews or when
the operator upgrades the plan, preserving the existing renewal behavior and
email-warning detail.
Source: MCP tools
1 participant
Summary
resolve_assetwith the public Free tier limits (500 credits/month, 1-year history, 15 req/s, HTTP 429 when exhausted).docs/SOURCES_WITH_AUTH.mdand points to dated public docs (maisretorno.com/mcp,developers.maisretorno.com, 2026-08-12).Test plan
bash scripts/ship/preflight.shon4c4de9f(ruff/mypy/pytest)git diff --checkReview evidence
4c4de9f. Cross-family attempt via Taskadversarial-reviewer(Cursor subagent). Label:EXTERNAL_SAME_FAMILYif same host pool, otherwise treat as external harness pass.AGENT_DATA(docs only; no MCP catalog/runtime change)origin/main4c4de9fPASSNO_FINDINGS— no secrets, no wiring, cascade remains stub-only; docs state operator-owned credentials and Free quota limits.NO_FINDINGS— docs-only clarification.Made with Cursor
Summary by CodeRabbit