# Private Apps Script + Gemini starter

This is a small teaching project, not a production service. The website labs never connect to Google. The Code.gs functions make real calls only when you run them in your own Apps Script project.

## 1. Prepare
- Create a disposable Google Sheet with fictional data. Open Extensions → Apps Script and paste Code.gs into the editor.
- Read every function before running it. There are no triggers, public web endpoints, mail sending, permission changes or deletion calls.
- Review your organization's rules before sending any real data to an API. API access, billing and Workspace subscriptions are separate concerns.

## 2. Configure
- Follow https://ai.google.dev/gemini-api/docs/api-key to create/configure your own Gemini Developer API project and key.
- In Apps Script Project Settings → Script Properties, add `GEMINI_API_KEY` and `GEMINI_MODEL`.
- Set `GEMINI_MODEL` to a current compatible bare model ID, verified at https://ai.google.dev/gemini-api/docs/models. Do not include `models/` or use the placeholder.
- This starter uses the generateContent REST track, currently labeled legacy in Google documentation: https://ai.google.dev/gemini-api/docs/generate-content/text-generation . Current Interactions examples have different fields; do not mix their parser with this starter.
- Never paste a real key into the public learning studio, a sheet cell, a browser script, logs or exported learning notes. Project editors can access Script Properties; restrict editors. Script Properties are not a secret vault against those editors.

## 3. Test without an API call
Run `testParserFixtures`. It checks accepted text, excluded thought parts, incomplete/blocked responses and text protection. Passing proves local parser behavior only.

## 4. Make one real call
Run `testGeminiConnection` manually and review the Apps Script authorization request. UrlFetchApp requires external-request authorization; other included services can affect the scopes detected for the project. API requests may incur charges. The function logs only a response-length summary. Inspect the returned text in a private debugging session or move to a fictional draft example to inspect the content.

The wrapper makes ONE request. No automatic retry, output-token limit or budget enforcement is configured. Add a model-compatible output limit only after checking current documentation. The source and response character limits are application guardrails, not token limits. Script runtime and API quotas still apply.

## 5. Try a small Sheets workflow
Create a sheet named `Feedback`, with exact A1:D1 headers:

ID | Input | Status | Draft

Add three fictional rows with unique IDs, comments in Input, `PENDING` in Status and an empty Draft. Run `processFeedbackDemo` manually. The demo supports at most 20 data rows and attempts at most three calls per run. It checks elapsed time before each new call; a single slow fetch can still overrun the intended budget. DONE means generation was written, not human approval. Review each draft against the input.

Completed/existing drafts are skipped. A generation failure stops the run, leaves the failed row PENDING and reports a sanitized error. Previous writes can remain DONE. Inspect before rerunning, since a lost response or interrupted write may have already consumed API resources. Duplicate IDs are rejected before calls. A changed row is skipped and counted as review; do not edit or sort the sheet during this learning demo. A script lock does not stop human edits or guarantee exactly-once processing. The recheck and write are not an atomic transaction.

Formula-like output receives an apostrophe prefix. Verify display and stored values with a disposable sheet; do not remove this policy without replacing it deliberately.

## 6. Try other fictional examples
- `createFictionalBriefingDemo`: one API call, then a NEW draft Doc in your Drive. No existing document is overwritten, and sharing is not changed. Reruns create additional documents.
- `draftFictionalReplyDemo`: one API call returning reply text. It does not read Gmail, create a Gmail draft or send a message.
- Form-to-review project: an architecture brief, not an installed trigger or complete queue implementation.

## Before expanding
Add identity checks, approved input boundaries, durable job states, considered retry policy, review rules, logging, spending controls and a stop/recovery procedure. Verify model/API changes with the same test cases. Review deployment identity before exposing server functions. Check current quotas and pricing in official documentation; this starter promises no free allowance or model availability.