[docs] add new comparison docs

[hellovai]

Important

Adds new comparison documentation for BAML against AI SDK, Langchain, Marvin, OpenAI SDK, and Pydantic, and updates the documentation navigation to include these comparisons.

• New Comparison Docs:
  • Adds ai-sdk.mdx, langchain.mdx, marvin.mdx, openai-sdk.mdx, and pydantic.mdx to compare BAML with AI SDK, Langchain, Marvin, OpenAI SDK, and Pydantic.
  • Each document details the limitations of the compared tool and the advantages of using BAML.
• Documentation Navigation:
  • Updates docs.yml to include new comparison pages under the "Comparisons" section.
  • Adds a new page "Why BAML?" to explain the benefits and use cases of BAML.

^{This description was created by for 17c8bd1. You can customize this summary. It will automatically update as commits are pushed.}

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
baml	❌ Failed (Inspect)			Jul 2, 2025 3:04am

[ellipsis-dev]

Important

Looks good to me! 👍

Reviewed everything up to a877334 in 1 minute and 47 seconds. Click for details.

• Reviewed 1106 lines of code in 4 files
• Skipped 0 files when reviewing.
• Skipped posting 6 draft comments. View those below.
• Modify your settings and rules to customize what types of comments Ellipsis leaves. And don't forget to react with 👍 or 👎 to teach Ellipsis.

1. fern/01-guide/09-comparisons/ai-sdk.mdx:61

• Draft comment:
  Clarify that 'complexResumeText' is a placeholder and note its expected type.
• Reason this comment was not posted:
  Comment did not seem useful. Confidence is useful = 0% <= threshold 50% The comment is asking for clarification on a placeholder and its expected type. This seems to be a request for more information, which is not allowed by the rules. The comment does not provide a specific code suggestion or ask for a test to be written. It is more of a request for documentation or clarification, which is not permitted.

2. fern/01-guide/09-comparisons/ai-sdk.mdx:97

• Draft comment:
  Consider mentioning alternatives to include enum value descriptions, since comments aren’t sent to the model.
• Reason this comment was not posted:
  Comment looked like it was already resolved.

3. fern/01-guide/09-comparisons/langchain.mdx:29

• Draft comment:
  Add an explicit import for 'List' from the typing module to support type hints.
• Reason this comment was not posted:
  Decided after close inspection that this draft comment was likely wrong and/or not actionable: usefulness confidence = 10% vs. threshold = 50% This is a documentation file showing example code. While technically correct that List should be imported, this is a minor detail in what's meant to be illustrative example code. The focus is on demonstrating Langchain functionality, not Python import best practices. Including every import would make the examples more verbose and distract from the main points. The missing import could confuse readers who copy-paste the code directly. Good documentation should be runnable without modification. The target audience is developers who understand Python basics. The missing List import is a trivial fix that most developers can handle, and keeping it makes the examples more concise and focused on Langchain concepts. Delete the comment. In documentation examples, we should optimize for clarity and conciseness over technical completeness when the missing details are trivial.

4. fern/01-guide/09-comparisons/openai-sdk.mdx:35

• Draft comment:
  Consider adding a note advising on robust error handling when using client.beta.chat.completions.parse in production code.
• Reason this comment was not posted:
  Decided after close inspection that this draft comment was likely wrong and/or not actionable: usefulness confidence = 10% vs. threshold = 50% This is a tutorial that follows a clear pedagogical structure - it starts with simple examples and gradually introduces complexity including error handling. Adding error handling to the first example would make it more confusing for readers trying to understand the basic concept. The error handling is covered properly later in the document. Perhaps some readers might copy-paste the initial example without reading further and deploy it without error handling. The document's structure deliberately builds complexity gradually and explicitly covers production concerns including error handling later. Adding complexity too early would harm the learning experience. Delete the comment. The document already covers error handling in an appropriate place, and adding it earlier would harm the pedagogical flow.

5. fern/docs.yml:430

• Draft comment:
  Verify that the new navigation links ('BAML vs Ai-SDK' and 'BAML vs OpenAI SDK') have consistent icons and correct paths.
• Reason this comment was not posted:
  Comment did not seem useful. Confidence is useful = 0% <= threshold 50% The comment is asking the PR author to verify consistency and correctness, which violates the rule against asking for confirmation or verification. It does not provide a specific suggestion or point out a specific issue.

6. fern/docs.yml:430

• Draft comment:
  Typo: 'Ai-SDK' seems to have inconsistent capitalization. Consider changing it to 'AI-SDK' for consistency with other acronyms.
• Reason this comment was not posted:
  Decided after close inspection that this draft comment was likely wrong and/or not actionable: usefulness confidence = 0% vs. threshold = 50% While the comment suggests a reasonable change for acronym capitalization, it's a very minor UI/styling issue. The rules specifically state not to comment on UI/styling changes and to assume the author made UI choices correctly. Even though this is a new addition, we should trust the author's styling choice. The capitalization of 'AI' is a common convention, so maybe this is worth fixing? But then again, 'Ai-SDK' could be an intentional brand name. The rules are clear about not commenting on UI and styling choices. Even if 'AI' is commonly capitalized, we should respect the author's choice in how they want to display product/brand names. Delete this comment as it violates the rule about not commenting on UI/styling changes.

Workflow ID: wflow_NdxUbVWKzcuTfKQc

^{You can customize by changing your verbosity settings, reacting with 👍 or 👎, replying to comments, or adding code review rules.}

[ellipsis-dev]

Important

Looks good to me! 👍

Reviewed 17c8bd1 in 45 seconds. Click for details.

• Reviewed 858 lines of code in 8 files
• Skipped 0 files when reviewing.
• Skipped posting 4 draft comments. View those below.
• Modify your settings and rules to customize what types of comments Ellipsis leaves. And don't forget to react with 👍 or 👎 to teach Ellipsis.

1. .claude/settings.local.json:11

• Draft comment:
  Added WebFetch permissions look correct – please double-check that these domains are intended to be allowed.
• Reason this comment was not posted:
  Comment did not seem useful. Confidence is useful = 0% <= threshold 50% The comment is asking the PR author to double-check the domains allowed for WebFetch permissions. This falls under asking the author to confirm their intention, which is against the rules. The comment does not provide a specific suggestion or point out a specific issue.

2. fern/01-guide/09-comparisons/pydantic.mdx:128

• Draft comment:
  When the LLM returns a non-list JSON object, the code wraps it using 'ResumeArray(**parsed)', but ResumeArray is designed as a wrapper with a 'resumes' field. Consider revising this logic to either directly validate a single Resume (e.g. using Resume.model_validate_json) or correctly instantiate ResumeArray (e.g. ResumeArray(resumes=[...])).
• Reason this comment was not posted:
  Comment was not on a location in the diff, so it can't be submitted as a review comment.

3. fern/01-guide/09-comparisons/pydantic.mdx:106

• Draft comment:
  The regex used for extracting the JSON block (re.search(r"{.*?}", ...)) may not handle nested JSON objects reliably. Consider using a more robust JSON extraction method if nested braces are expected.
• Reason this comment was not posted:
  Comment was not on a location in the diff, so it can't be submitted as a review comment.

4. fern/docs.yml:1

• Draft comment:
  This docs.yml configuration is very comprehensive. Please ensure that all redirect rules and navigation paths remain consistent with the latest site structure.
• Reason this comment was not posted:
  Comment was not on a location in the diff, so it can't be submitted as a review comment.

Workflow ID: wflow_rAXmFF8wn9JnYd6h

^{You can customize by changing your verbosity settings, reacting with 👍 or 👎, replying to comments, or adding code review rules.}