Improve the README and add practical examples in a `samples/` directory

[aubrypaul]

The README should be improved to help users understand how to use the library through concrete, practical examples.

The documentation should not focus on installation, since setup only requires dragging and dropping the file. The main priority is to provide a wide range of usage examples in a dedicated samples/ directory, with the README linking to and briefly explaining each sample.

Suggested additions

• Add a samples/ directory with multiple self-contained examples.
• Add a README section that lists the available samples and explains what each one demonstrates.
• Include examples for basic usage, common workflows, advanced usage, error handling, configuration, and integrations.
• Add examples for different real-world situations so users can quickly find a sample close to their own use case.
• Keep each sample focused on one clear scenario.
• For each sample, include:
• what the sample demonstrates
• when to use it
• required configuration, if any
• copy-pasteable code
• expected behavior or output

Acceptance criteria

• A samples/ directory is added.
• The README links to the samples/ directory.
• The README briefly explains the purpose of each sample.
• The samples/ directory contains a broad range of practical examples.
• Examples cover simple, intermediate, and more advanced use cases.
• At least one integration-oriented example is included.
• The examples are clear, practical, and easy to adapt.

[aubrypaul]

@coderabbitai plan this issue for codex

[coderabbitai]

Coding Plan

Summary

• Create 14 focused sample files in samples/ covering the full spectrum from basic chat to advanced RAG and MCP connectors
• Follow a consistent sample structure: header documentation, minimal runnable code, clear expected behavior
• Update README to serve as a navigation hub pointing users to samples by use case
• Ensure all samples are self-contained, copy-pasteable, and demonstrate exactly one clear scenario

Implementation Steps

Phase 1: Create Samples Directory with Practical Examples

Create a comprehensive samples/ directory containing focused, self-contained examples that progress from basic to advanced usage patterns. Each sample file should follow a consistent structure: header comment explaining what it demonstrates, when to use it, required configuration, the executable code, and expected behavior.

Task 1: Create Basic Usage Samples

Establish foundational examples that newcomers can use to get started immediately.

• Create samples/simple-chat.gs demonstrating the minimal hello-world pattern: set API key, create chat, add message, run, log response
• Create samples/system-prompts.gs showing how to set assistant personality and context using system messages with addMessage(content, true)
• Create samples/multi-model-usage.gs illustrating how to use the same chat setup with different models (GPT, Gemini, reasoning models) via the model parameter in run()
• Each file should include a header block with: purpose, use case, required config (API keys), and expected output description

Task 2: Create Function Calling Samples

Demonstrate the tool/function calling capabilities that enable AI to execute code.

• Create samples/function-calling-basics.gs showing a simple single-function setup: define function with newFunction(), add parameters, register with chat, and let the model invoke it
• Create samples/function-calling-advanced.gs demonstrating endWithResult(true) for early termination, onlyReturnArguments(true) for argument extraction without execution, and multiple function registration
• Include stub function implementations (like the getWeather pattern in testFunctions.gs) so samples are runnable

Task 3: Create Content Analysis Samples

Show how to analyze various content types (web, images, documents).

• Create samples/web-browsing.gs demonstrating enableBrowsing(true) for real-time web search and domain-restricted browsing
• Create samples/image-analysis.gs showing addImage() with both URL and Blob inputs for vision capabilities
• Create samples/document-analysis.gs demonstrating addFile() with Drive file IDs and Blobs for PDF/document analysis
• Create samples/knowledge-links.gs showing addKnowledgeLink(url) for injecting web page content as context

Task 4: Create Advanced Feature Samples

Cover sophisticated features for power users.

• Create samples/vector-store-rag.gs demonstrating the full vector store workflow: create store, upload files with attributes, attach to chat, query, and optionally use onlyReturnChunks()
• Create samples/mcp-connectors.gs showing Google Workspace connector setup (Gmail, Calendar, Drive) with newConnector(), setConnectorId(), and authorization
• Create samples/conversation-continuation.gs demonstrating multi-turn conversations using setPreviousResponseId() and retrieveLastResponseId()
• Create samples/vertex-ai-setup.gs showing GCP authentication via setGeminiAuth(projectId, region) as an alternative to API keys

Task 5: Create Configuration and Integration Samples

Demonstrate operational controls and real-world integration patterns.

• Create samples/configuration-options.gs covering: setMaximumAPICalls() for budget control, warnIfResponseTokenUsageAbove() for monitoring, disableLogs() for output control, and enableCompaction() with threshold
• Create samples/sheets-ai-assistant.gs as the integration example: read data from active sheet, send to AI for analysis/summarization, write results back — demonstrating a complete Apps Script workflow
• Ensure the Sheets example shows practical patterns like reading ranges, formatting prompts with data, and handling responses

🤖 Prompt for AI agents

Create a `samples/` directory at the project root and populate it with 14
focused, self-contained `.gs` sample files. Each file must follow a consistent
structure: a header block comment describing the purpose, use case, required
config (API keys), and expected output, followed by minimal runnable code
demonstrating exactly one clear scenario.

**Task 1.1 — Basic Usage (`samples/simple-chat.gs`, `samples/system-prompts.gs`,
`samples/multi-model-usage.gs`)**
- `simple-chat.gs`: Minimal hello-world pattern — set API key, create chat with
`newChat()`, add a message, call `run()`, log the response
- `system-prompts.gs`: Show how to set assistant personality/context using
system messages via `addMessage(content, true)`
- `multi-model-usage.gs`: Demonstrate reusing the same chat setup across
different models (GPT, Gemini, reasoning models) by varying the `model`
parameter in `run()`

**Task 1.2 — Function Calling (`samples/function-calling-basics.gs`,
`samples/function-calling-advanced.gs`)**
- `function-calling-basics.gs`: Single-function setup — define a function with
`newFunction()`, add parameters, register it with the chat, and let the model
invoke it; include a stub implementation (e.g., `getWeather` pattern from
`testFunctions.gs`)
- `function-calling-advanced.gs`: Demonstrate `endWithResult(true)` for early
termination, `onlyReturnArguments(true)` for argument extraction without
execution, and multiple function registration; include stub implementations

**Task 1.3 — Content Analysis (`samples/web-browsing.gs`,
`samples/image-analysis.gs`, `samples/document-analysis.gs`,
`samples/knowledge-links.gs`)**
- `web-browsing.gs`: Use `enableBrowsing(true)` for real-time web search and
domain-restricted browsing
- `image-analysis.gs`: Demonstrate `addImage()` with both URL and Blob inputs
for vision capabilities
- `document-analysis.gs`: Use `addFile()` with Drive file IDs and Blobs for
PDF/document analysis
- `knowledge-links.gs`: Use `addKnowledgeLink(url)` to inject web page content
as context

**Task 1.4 — Advanced Features (`samples/vector-store-rag.gs`,
`samples/mcp-connectors.gs`, `samples/conversation-continuation.gs`,
`samples/vertex-ai-setup.gs`)**
- `vector-store-rag.gs`: Full vector store workflow — create store, upload files
with attributes, attach to chat, query, and optionally use `onlyReturnChunks()`
- `mcp-connectors.gs`: Google Workspace connector setup (Gmail, Calendar, Drive)
using `newConnector()`, `setConnectorId()`, and authorization
- `conversation-continuation.gs`: Multi-turn conversations using
`setPreviousResponseId()` and `retrieveLastResponseId()`
- `vertex-ai-setup.gs`: GCP authentication via `setGeminiAuth(projectId,
region)` as an alternative to API keys

**Task 1.5 — Configuration & Integration (`samples/configuration-options.gs`,
`samples/sheets-ai-assistant.gs`)**
- `configuration-options.gs`: Cover `setMaximumAPICalls()` for budget control,
`warnIfResponseTokenUsageAbove()` for monitoring, `disableLogs()` for output
control, and `enableCompaction()` with a threshold
- `sheets-ai-assistant.gs`: Full Apps Script integration — read data from the
active sheet, send it to AI for analysis/summarization, write results back; show
practical patterns like reading ranges, formatting prompts with data, and
handling responses

Phase 2: Update README Documentation

Revise the README to prominently feature the samples directory and guide users to appropriate examples based on their needs.

Task 1: Add Samples Reference Section

Create a new README section that serves as the primary guide to the examples.

• Add a "Samples" or "Examples" section near the top of README.md (after features, before detailed API reference)
• Organize samples into logical categories: Getting Started, Content Analysis, Function Calling, Advanced Features, Integration
• For each sample, include: one-line description, link to the file, and key methods/features demonstrated
• Use a table or structured list format for easy scanning

Task 2: Refine README Structure

Adjust the README to de-emphasize installation and better highlight practical usage.

• Keep installation section brief (setup is just drag-and-drop)
• Ensure the samples section is prominent and easy to find
• Add cross-references from the API documentation section to relevant samples where appropriate
• Consider adding a "Quick Start" subsection that points to simple-chat.gs as the first thing to try

🤖 Prompt for AI agents

Update `README.md` to add a prominent samples reference section and refine the
overall document structure.

**Task 2.1 — Add Samples Reference Section**
- Insert a new "Samples" or "Examples" section near the top of `README.md`,
positioned after the features section and before the detailed API reference
- Organize entries into logical categories: Getting Started, Content Analysis,
Function Calling, Advanced Features, Integration
- For each sample file, provide: a one-line description, a link to the file in
`samples/`, and the key methods/features it demonstrates
- Use a table or structured list format for easy scanning

**Task 2.2 — Refine README Structure**
- Keep the installation section brief, noting that setup is just drag-and-drop
- Ensure the samples section is easy to find and visually prominent
- Add cross-references from the API documentation section to relevant sample
files where appropriate
- Add a "Quick Start" subsection pointing to `samples/simple-chat.gs` as the
recommended first example to try

Research

GenAIApp is a Google Apps Script library providing a unified fluent API for building AI chat applications with OpenAI and Google Gemini models. The library exposes four main builders (newChat(), newFunction(), newConnector(), newVectorStore()) and authentication setters. The existing src/testFunctions.gs demonstrates testing patterns but lacks user-facing documentation examples. The current README covers features and API reference but would benefit from practical, scenario-based samples.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Create a `samples/` directory at the project root and populate it with 14
focused, self-contained `.gs` sample files. Each file must follow a consistent
structure: a header block comment describing the purpose, use case, required
config (API keys), and expected output, followed by minimal runnable code
demonstrating exactly one clear scenario.

**Task 1.1 — Basic Usage (`samples/simple-chat.gs`, `samples/system-prompts.gs`,
`samples/multi-model-usage.gs`)**
- `simple-chat.gs`: Minimal hello-world pattern — set API key, create chat with
`newChat()`, add a message, call `run()`, log the response
- `system-prompts.gs`: Show how to set assistant personality/context using
system messages via `addMessage(content, true)`
- `multi-model-usage.gs`: Demonstrate reusing the same chat setup across
different models (GPT, Gemini, reasoning models) by varying the `model`
parameter in `run()`

**Task 1.2 — Function Calling (`samples/function-calling-basics.gs`,
`samples/function-calling-advanced.gs`)**
- `function-calling-basics.gs`: Single-function setup — define a function with
`newFunction()`, add parameters, register it with the chat, and let the model
invoke it; include a stub implementation (e.g., `getWeather` pattern from
`testFunctions.gs`)
- `function-calling-advanced.gs`: Demonstrate `endWithResult(true)` for early
termination, `onlyReturnArguments(true)` for argument extraction without
execution, and multiple function registration; include stub implementations

**Task 1.3 — Content Analysis (`samples/web-browsing.gs`,
`samples/image-analysis.gs`, `samples/document-analysis.gs`,
`samples/knowledge-links.gs`)**
- `web-browsing.gs`: Use `enableBrowsing(true)` for real-time web search and
domain-restricted browsing
- `image-analysis.gs`: Demonstrate `addImage()` with both URL and Blob inputs
for vision capabilities
- `document-analysis.gs`: Use `addFile()` with Drive file IDs and Blobs for
PDF/document analysis
- `knowledge-links.gs`: Use `addKnowledgeLink(url)` to inject web page content
as context

**Task 1.4 — Advanced Features (`samples/vector-store-rag.gs`,
`samples/mcp-connectors.gs`, `samples/conversation-continuation.gs`,
`samples/vertex-ai-setup.gs`)**
- `vector-store-rag.gs`: Full vector store workflow — create store, upload files
with attributes, attach to chat, query, and optionally use `onlyReturnChunks()`
- `mcp-connectors.gs`: Google Workspace connector setup (Gmail, Calendar, Drive)
using `newConnector()`, `setConnectorId()`, and authorization
- `conversation-continuation.gs`: Multi-turn conversations using
`setPreviousResponseId()` and `retrieveLastResponseId()`
- `vertex-ai-setup.gs`: GCP authentication via `setGeminiAuth(projectId,
region)` as an alternative to API keys

**Task 1.5 — Configuration & Integration (`samples/configuration-options.gs`,
`samples/sheets-ai-assistant.gs`)**
- `configuration-options.gs`: Cover `setMaximumAPICalls()` for budget control,
`warnIfResponseTokenUsageAbove()` for monitoring, `disableLogs()` for output
control, and `enableCompaction()` with a threshold
- `sheets-ai-assistant.gs`: Full Apps Script integration — read data from the
active sheet, send it to AI for analysis/summarization, write results back; show
practical patterns like reading ranges, formatting prompts with data, and
handling responses
===============================================================================

Task: 2

Update `README.md` to add a prominent samples reference section and refine the
overall document structure.

**Task 2.1 — Add Samples Reference Section**
- Insert a new "Samples" or "Examples" section near the top of `README.md`,
positioned after the features section and before the detailed API reference
- Organize entries into logical categories: Getting Started, Content Analysis,
Function Calling, Advanced Features, Integration
- For each sample file, provide: a one-line description, a link to the file in
`samples/`, and the key methods/features it demonstrates
- Use a table or structured list format for easy scanning

**Task 2.2 — Refine README Structure**
- Keep the installation section brief, noting that setup is just drag-and-drop
- Ensure the samples section is easy to find and visually prominent
- Add cross-references from the API documentation section to relevant sample
files where appropriate
- Add a "Quick Start" subsection pointing to `samples/simple-chat.gs` as the
recommended first example to try

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!