Repository navigation
docs: document enrich(), plan(), MCP server, and Provider Batch mode - #185
Merged
Merged
Conversation
… mode Documents the four v1.11.0 features that landed undocumented: the enrich() front door, the plan() intent layer, the ondine-mcp server, and Provider Batch API execution mode (plus the RunRegistry backing it). Makes enrich() the quickstart's opening example, with the builder chain retained as the power-user path, and cross-references the new provider-batch guide against the pre-existing execution-modes guide (Standard/Async/Streaming) to avoid confusing the two senses of "execution mode". Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Contributor
📝 WalkthroughWalkthroughDocumentation updates reposition ChangesDocumentation guides
Estimated code review effort: 2 (Simple) | ~10 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 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}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 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/getting-started/quickstart.md`:
- Around line 60-65: Label the output fenced block in
docs/getting-started/quickstart.md lines 60-65 with the text language
identifier, and label the ValueError fenced block in docs/guides/mcp-server.md
lines 52-55 with text as well.
In `@docs/guides/enrich.md`:
- Line 28: Update the Builder API link in the enrich guide to use the current
Quickstart anchor `#5-builder-api-full-control` instead of the stale
`#4-builder-api-more-control` anchor.
In `@docs/README.md`:
- Line 33: Update the `enrich()` description in the README to qualify its
type-preservation behavior: state that pandas and Polars DataFrame inputs retain
their respective types, while file-path inputs return a pandas DataFrame.
🪄 Autofix (Beta)
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: ba19f85f-e2aa-4f0d-85d5-3ad2088d81c2
📒 Files selected for processing (8)
docs/README.mddocs/SUMMARY.mddocs/getting-started/quickstart.mddocs/guides/enrich.mddocs/guides/execution-modes.mddocs/guides/intent-planning.mddocs/guides/mcp-server.mddocs/guides/provider-batch.md
Comment on lines
+60
to
+65
| ``` | ||
| product brand | ||
| 0 iPhone 15 Pro Max 256GB Apple | ||
| 1 Samsung Galaxy S24 Ultra Samsung | ||
| 2 Google Pixel 8 Pro Google | ||
| ``` |
Contributor
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Add language identifiers to the fenced blocks.
Markdownlint reports MD040 for both fences. Use ```text for these output/error examples.
docs/getting-started/quickstart.md#L60-L65: label the output fence astext.docs/guides/mcp-server.md#L52-L55: label theValueErrorfence astext.
🧰 Tools
🪛 markdownlint-cli2 (0.23.1)
[warning] 60-60: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
📍 Affects 2 files
docs/getting-started/quickstart.md#L60-L65(this comment)docs/guides/mcp-server.md#L52-L55
🤖 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/getting-started/quickstart.md` around lines 60 - 65, Label the output
fenced block in docs/getting-started/quickstart.md lines 60-65 with the text
language identifier, and label the ValueError fenced block in
docs/guides/mcp-server.md lines 52-55 with text as well.
Source: Linters/SAST tools
| | Structured output | `schema=` kwarg | `.with_structured_output()` | | ||
| | Best for | Notebooks, scripts, first pass | Production configs, fine-grained control | | ||
|
|
||
| Reach for the [Builder API](../getting-started/quickstart.md#4-builder-api-more-control) when you need to name output columns per-column, tune retry policy, or wire checkpointing/observability explicitly. |
Contributor
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Fix the stale Quickstart anchor.
The Quickstart now uses ### 5. Builder API (Full Control), so #4-builder-api-more-control no longer resolves. Update the link to #5-builder-api-full-control.
🤖 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/guides/enrich.md` at line 28, Update the Builder API link in the enrich
guide to use the current Quickstart anchor `#5-builder-api-full-control` instead
of the stale `#4-builder-api-more-control` anchor.
| ## Key Features | ||
|
|
||
| - **Quick API** -- 3-line hello world with smart defaults | ||
| - **`enrich()`** -- one-call front door; input type in, same type out |
Contributor
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Qualify the type-preservation claim.
enrich() preserves pandas/Polars DataFrame types, but a file path returns a pandas DataFrame. Replace “same type out” with wording that reflects this distinction.
🤖 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/README.md` at line 33, Update the `enrich()` description in the README
to qualify its type-preservation behavior: state that pandas and Polars
DataFrame inputs retain their respective types, while file-path inputs return a
pandas DataFrame.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds documentation for the four v1.11.0 features that landed on
mainundocumented:docs/guides/enrich.md— theondine.enrich()one-call front door: signature, input-type preservation (pandas/polars/path),schema=structured output + auto JSON parser injection, and the explicit kwargs allowlist (TypeErroron typos).docs/guides/intent-planning.md— theondine.plan()intent layer: thePlanobject (.specifications,.goal,.rationale,.estimated_cost,.preview_yaml(),.build()), and the safety model — one structured LLM call to draft a spec, inspectable/approvable before anything executes, explicitly not an agent loop.docs/guides/mcp-server.md— theondine-mcpserver: install viapip install ondine[mcp], a copy-pasteable MCP client config snippet, the four tools (ondine_estimate/ondine_run/ondine_status/ondine_collect), the non-blockingondine_runcontract, and the mandatory-positive-budget guard for agent-initiated runs.docs/guides/provider-batch.md— Provider Batch API execution mode: OpenAI/Anthropic-only guard (raised at.build()time), the submit/poll/collect job lifecycle, crash-safety via the RunRegistry, and the RunRegistry itself (SQLite-backed, lives in the checkpoint dir).Naming collision resolved:
docs/guides/execution-modes.mdalready existed for Ondine's own Standard/Async/Streaming engines (a different sense of "execution mode" thanwith_execution_mode("provider_batch")). Left that page untouched and named the new pageprovider-batch.md("Provider Batch API Mode"), with a cross-reference note added to the top of each page pointing at the other so readers aren't confused by the two meanings.Also:
docs/SUMMARY.md— registered all four new pages (Pipeline Guides section forenrich/plan/Provider Batch, Reference section for MCP Server).docs/getting-started/quickstart.md—enrich()is now the opening "Simplest" example;QuickPipelineand the builder chain are retained afterward as progressively more explicit/powerful options.docs/README.md— Quick Start example switched toenrich(); Key Features list now mentionsenrich(),plan(), the MCP server, and Provider Batch mode.No numbers were invented: the ~50% Batch API discount is attributed as a provider claim ("OpenAI and Anthropic advertise ~50%"), not presented as measured.
benchmarks/RESULTS.mddoesn't contain batch-mode-specific figures, so none are cited.Test plan
uv run ruff check docs/— no findings (ruff doesn't lint Markdown; the 14 pre-existing findings underbenchmarks/are untouched by this change).inspect.signature(ondine.enrich),inspect.signature(plan),Pipeline.submit/Pipeline.attach,MCPService.ondine_*methods,SUPPORTED_BATCH_PROVIDERS.enrich(),plan(), and Provider Batch guard code samples against the real package (LLM calls mocked at thePipeline.execute/structured_invokeboundary) — outputs match what's documented verbatim, including exactTypeError/ValueErrormessages quoted in the docs.uv run pytest tests/unit/test_enrich.py tests/unit/test_planner.py -q— 30 passed.docs/SUMMARY.md.ai assistance: i directed this work with help from claude code.
Summary by CodeRabbit
enrich()workflow, including inputs, outputs, structured responses, and supported options.plan(), including validation, cost estimates, and pipeline building.