Docs/howto-texttosqlagent (#2264)

New things added in this PR are: 
- A new how-to guide `docs/howtos/applications/text2sql.md`
- A new example module `examples/ragas_examples/text2sql/` to accompany
the guide

## Changes Made

- **Added "How to evaluate a Text to SQL Agent" Guide**: A new how-to
guide (`docs/howtos/applications/text2sql.md`) was created. It walks
users through setting up, evaluating, and iteratively improving a
text-to-SQL system.
- **Created a Full Text-to-SQL Example**: A new, installable example
module (`ragas_examples.text2sql`) has been added. This module is
self-contained and provides all the necessary components to follow the
guide:
- **`Text2SQLAgent`**: A configurable agent (`text2sql_agent.py`) that
uses OpenAI models to convert natural language to SQL, featuring
comprehensive tracing.
- **Evaluation Pipeline**: An evaluation script (`evals.py`) built with
the Ragas experimentation framework, including custom metrics for
`sql_validity` and `execution_accuracy`.
- **Error Analysis Tool**: An automated script (`analyze_errors.py`)
that uses an LLM to categorize failure modes in evaluation results,
helping to guide system improvements.
- **Data and DB Utilities**: Scripts to download and prepare the BookSQL
dataset (`data_utils.py`) and a robust database utility module
(`db_utils.py`) for query execution and schema handling.
- **Iterative Prompts**: Includes multiple prompt versions
(`prompt.txt`, `prompt_v2.txt`, `prompt_v3.txt`) to demonstrate the
iterative improvement process described in the guide.

## Testing

### How to Test

-   [ ] Manual testing steps:
1. Follow the instructions in the new
`docs/howtos/applications/text2sql.md` guide.
2. Install the required dependencies with `uv pip install
"ragas-examples[text2sql]"`.
    3.  Set the `OPENAI_API_KEY` environment variable.
4. Run the data preparation commands, evaluation commands, and error
analysis commands as specified in the guide.
5. Verify that the commands execute successfully and the outputs are
consistent with the examples provided in the documentation.

## References

-   Documentation: `docs/howtos/applications/text2sql.md`

Author: sanjeed5

.cursor/commands/git-pr.md

@@ -0,0 +1,37 @@
+Review the PR and create PR description in this format:
+
+## Issue Link / Problem Description
+<!-- Link to related issue or describe the problem this PR solves -->
+- Fixes #[issue_number]
+- OR describe the issue: What problem does this solve? How can it be replicated?
+
+## Changes Made
+<!-- Describe what you changed and why -->
+- 
+- 
+- 
+
+## Testing
+<!-- Describe how this should be tested -->
+### How to Test
+- [ ] Automated tests added/updated
+- [ ] Manual testing steps:
+  1. 
+  2. 
+  3. 
+
+## References
+<!-- Link to related issues, discussions, forums, or external resources -->
+- Related issues: 
+- Documentation: 
+- External references: 
+
+## Screenshots/Examples (if applicable)
+<!-- Add screenshots or code examples showing the change -->
+
+---
+<!-- 
+Thank you for contributing to Ragas! 
+Please fill out the sections above as completely as possible.
+The more information you provide, the faster your PR can be reviewed and merged.
+-->

.cursor/rules/docs-diataxis-guidelines.mdc

@@ -41,9 +41,11 @@ When writing or editing documentation, categorise each page as **one** of the fo
 Choose → Assess → Decide → Do. Focus on small, atomic upgrades rather than grand rewrites.
 
 ### Writing Style
-• Use second-person (“you”) and active voice.
+• Use second-person ("you") and active voice.
 • Ensure code blocks are **copy-pasteable** and include necessary context (imports, environment).
 • Prefer short sentences; use Markdown admonitions (`!!! note`, `!!! warning`) sparingly for important side-information.
+• Use `??? "Click to expand"` collapsible admonitions to contain outputs, long prompts, verbose logs, or any content that would clutter the main article flow. This keeps the primary content scannable while preserving detailed information for readers who need it.
+• **Always add a blank line after text ending with a colon before starting a list.** This ensures proper Markdown rendering in MkDocs. Without the blank line, list items may render as continuation text instead of a proper bulleted/numbered list.
 
 ### Cross-linking Between Modes
 • End tutorials with pointers to relevant how-to guides for further exploration.

.cursor/rules/update-guide.mdc

@@ -0,0 +1,6 @@
+---
+alwaysApply: false
+---
+We are writing a how to guide for Ragas docs and Ragas users.
+
+So after any coding step we complete, or after any succesful runs, always update the guide with what was done. 

.gitignore

@@ -189,3 +189,4 @@ examples/dist/
 examples/build/
 examples/*.egg-info/
 examples/ragas_examples/_version.py
+examples/ragas_examples/text2sql/experiments/*

docs/howtos/applications/index.md

@@ -16,4 +16,8 @@ usecases to solve problems you might encounter when you're building.
 - [Single-hop Query Testset](singlehop_testset_gen.md)
 
 ## Benchmarking
-- [Benchmarking Gemini models](gemini_benchmarking.md)
+- [Benchmarking Gemini models](gemini_benchmarking.md)
+
+## Agent Evaluation
+
+- [Evaluate a Text-to-SQL Agent](text2sql.md)