docs: align AI examples with the actual SDK API and return shapes

[AbdulWasih05]

What

Aligns the AI examples in README.md and SDK-REFERENCE.md (and one ai.ts JSDoc example) with the AI module's actual API and return shapes.

Why

The docs referenced methods that don't exist (ai.completion, ai.vision) and destructured responses incorrectly ({ data, error }, chat.response, images.images[0].url).

Copy-pasting these examples fails at runtime or teaches the wrong return shape.

How

• README

  • Replaced the ai.completion / ai.vision examples with:
    • ai.chat.completions.create
    • ai.images.generate
    • ai.embeddings.create
  • Added a note that AI methods return OpenAI-style response objects directly and throw on failure.

• SDK-REFERENCE

  • Corrected chat, streaming, image, and embeddings examples to use the actual response shapes.
  • Updated parameter lists to match @insforge/shared-schemas request schemas.
  • Removed fictional image parameters.
  • Removed nonexistent chat parameters (message, systemPrompt).
  • Added an embeddings section.

• ai.ts

  • Fixed the images.generate JSDoc example to use data[0].b64_json.
  • Removed the incorrect images[0].url reference.

How to Test

npm run typecheck
npm test

Expected results:

• npm run typecheck -- passes
• npm test -- 131/131 tests pass
• Cross-checked against:
  • @insforge/shared-schemas@1.1.53
  • integration-tests/ai.test.ts

Related

Closes #76

---

Summary by cubic

Aligns AI examples in README and SDK reference to the actual SDK API and return shapes so copy‑paste works and matches OpenAI‑like responses. Also fixes the images.generate JSDoc example and updates params to match @insforge/shared-schemas. Closes #76.

• Bug Fixes
  • Replaced ai.completion/ai.vision with ai.chat.completions.create, ai.images.generate, ai.embeddings.create.
  • Corrected return handling: choices[0].message.content, streaming choices[0].delta.content, images data[0].b64_json, embeddings data[0].embedding; methods throw on failure.
  • Synced parameter lists with @insforge/shared-schemas (removed nonexistent chat/image params; added embeddings and documented supported options).
  • Fixed ai.ts JSDoc to use response.data[0].b64_json.

^{Written for commit 06854de. Summary will update on new commits.}

Note

Align AI SDK docs and JSDoc examples with OpenAI-like return shapes

• Updates README.md and SDK-REFERENCE.md to remove the { data, error } envelope pattern and replace it with direct return values that throw on failure, matching the actual SDK API.
• Rewrites chat completion examples to use insforge.ai.chat.completions.create and read from choices[0].message.content (non-streaming) and choices[0]?.delta?.content (streaming).
• Updates image generation examples to read base64 from image.data[0].b64_json and adds an image-to-image example; adds a new embeddings section using ai.embeddings.create returning vectors via embeddings.data[i].embedding.
• Fixes the Images.generate JSDoc in src/modules/ai.ts to reference response.data[0].b64_json instead of response.images[0].url.

^{Macroscope summarized 06854de.}

Summary by CodeRabbit

• Documentation
  • Updated API documentation and examples to reflect new OpenAI-compatible response object formats for AI features.
  • Refreshed examples for chat completions, streaming, image generation, and embeddings with current response structures.

[coderabbitai]

Walkthrough

This PR aligns README and SDK reference documentation with the actual AI module API. Chat completions, images, and embeddings examples now correctly demonstrate thrown-on-failure OpenAI-like response objects and proper accessor patterns for streaming deltas and image base64 output.

Changes

AI API Shape Documentation Updates

Layer / File(s)	Summary
README quick start examples README.md	Replaced ai.completion and ai.vision examples with correct APIs: ai.chat.completions.create() (non-streaming and streaming), ai.images.generate() returning base64 data, and ai.embeddings.create() with embedding vectors.
SDK-REFERENCE comprehensive documentation SDK-REFERENCE.md	Updated chat completions examples to use direct return objects instead of { data, error } destructuring, documented streaming via choices[0].delta.content, expanded parameters list, and revised images and embeddings examples to show correct response accessor patterns.
Source module documentation example src/modules/ai.ts	Updated Images class JSDoc example to read base64 output from response.data[0].b64_json instead of the prior response.images[0].url pattern.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐰 A hop through the docs, old code made new,
Chat streams and images in shades of true,
No more the phantom ai.vision calls,
Just OpenAI shapes adorning the halls.
The SDK whispers: "I'm real, aligned, and free!" ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically describes the main change: updating documentation examples to align with the actual SDK API and return shapes.
Linked Issues check	✅ Passed	The pull request fully addresses all coding requirements from issue #76: removes nonexistent ai.completion and ai.vision examples, updates to actual APIs (chat.completions.create, images.generate, embeddings.create), and corrects response shapes throughout documentation.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to documentation updates in README.md, SDK-REFERENCE.md, and a single JSDoc example in ai.ts—entirely aligned with the objective to fix documentation drift.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[cubic-dev-ai]

No issues found across 3 files

_{Re-trigger cubic}

[agent-zhang-beihai]

Code Review — PR #89 docs: align AI examples with the actual SDK API and return shapes

Scope: 3 files changed (README.md +37, SDK-REFERENCE.md +122, src/modules/ai.ts +2). The only runtime-visible change is a one-line JSDoc fix in ai.ts; everything else is documentation.

---

Summary

The direction of this PR is unambiguously correct. The old examples referenced methods that don't exist (ai.completion, ai.vision), used a { data, error } envelope the AI module never returns, and read non-existent fields (chat.response, images.images[0].url). The replacements are consistent with the OpenAI-like response objects the SDK actually returns and with how for await async iterables work. The single code change (response.images[0].url → response.data[0].b64_json in the JSDoc) is correct.

---

Findings

Important — worth a follow-up

1. Model name google/gemini-3-pro-image-preview is unverified (README.md line 270, SDK-REFERENCE.md lines 749, 824)

   The PR replaces google/gemini-2.5-flash-image-preview (a plausible, real-sounding identifier) with google/gemini-3-pro-image-preview in every image example, but the PR description does not cite evidence that this string is a live model in InsForge's platform. If the identifier isn't registered, every copy-pasted image example throws at runtime. The PR claims cross-checking against integration tests — if an integration test actually calls this model, the concern is resolved; a pointer to that test would be reassuring.

Low — inconsistency / cosmetic

2. Streaming null-delta pattern differs between README and SDK-REFERENCE (README.md line 261 vs SDK-REFERENCE.md lines 717, 818)

   README writes:

   process.stdout.write(chunk.choices[0]?.delta?.content ?? "");

   SDK-REFERENCE writes:

   const delta = chunk.choices[0]?.delta?.content;
   if (delta) process.stdout.write(delta);

   Both are functionally correct (OpenAI final chunks have null content, and null ?? "" = "" which is harmless; if (null) is also skipped). But they teach two different idioms in the same PR. The if (delta) form is arguably cleaner and avoids a no-op write. Aligning them removes reader confusion.

3. encoding_format is snake_case; TypeScript callers may need camelCase (SDK-REFERENCE.md line 789)

   - `encoding_format` ('float' | 'base64'): Encoding of the returned vectors

   OpenAI's own TypeScript SDK exposes this property as encoding_format (snake_case) on the request type, so if InsForge mirrors that convention this is correct. But if the InsForge TypeScript interface uses encodingFormat (camelCase, the typical TS convention), copy-pasting would produce a TS type error or a silently-ignored unknown key. Worth double-checking against the actual schema type.

4. README omits the data: URI caveat that SDK-REFERENCE includes (README.md line 275)

   SDK-REFERENCE helpfully notes // base64-encoded image (no data: URI prefix), but README just says:

   const base64Png = image.data[0].b64_json;

   A web developer reading only README may paste the value directly into <img src=...> expecting a data URI and get a broken image silently. A brief parenthetical // raw base64, no data: prefix would close the gap.

---

Verdict

No Critical or blocking Important issues — the one Important item (model name) is flagged for follow-up, not blocking. The overall change is a clear net improvement to the developer experience.

Ahead Four.

[AbdulWasih05]

hey @jwfing, both gemini-2.5-flash-image-preview and gemini-3-pro-image-preview are registered in architecture.mdx. I used gemini-3-pro-image-preview to match the canonical TS docs (ai.mdx), but the skills repo uses gemini-2.5-flash-image. Which would you prefer the SDK examples standardize on

[jwfing]

@AbdulWasih05 yes, I know that gemini-3-pro-image-preview is valid and also agree with you to use the latest model.
Thanks for your contribution.