[Vertex GA] Regenerate docs after Vertex GA changes #8505

hsubox76 · 2024-09-17T18:23:58Z

Regenerated docs based on all code changes for Vertex GA so far.

Changes are:

added Schema classes
remove "unspecified" enum values
change optionality on some properties

google-oss-bot · 2024-09-17T18:39:09Z

Size Report ¹

Affected Products

@firebase/vertexai
Type Base (45e0afe) Merge (fa7f743) Diff
browser 28.3 kB 28.4 kB +25 B (+0.1%)
main 29.2 kB 29.2 kB +25 B (+0.1%)
module 28.3 kB 28.4 kB +25 B (+0.1%)
firebase
Type Base (45e0afe) Merge (fa7f743) Diff
firebase-vertexai.js 21.9 kB 22.0 kB +42 B (+0.2%)

Test Logs

https://storage.googleapis.com/firebase-sdk-metric-reports/lXkjBGDKfQ.html

google-oss-bot · 2024-09-17T18:50:48Z

Size Analysis Report ¹

Affected Products

@firebase/vertexai
- ChatSession
  Size
  Type Base (45e0afe) Merge (fa7f743) Diff
  size 14.4 kB 14.4 kB +27 B (+0.2%)
  size-with-ext-deps 32.9 kB 32.9 kB +27 B (+0.1%)
- GenerativeModel
  Size
  Type Base (45e0afe) Merge (fa7f743) Diff
  size 16.9 kB 16.9 kB +27 B (+0.2%)
  size-with-ext-deps 35.4 kB 35.4 kB +27 B (+0.1%)
- getGenerativeModel
  Size
  Type Base (45e0afe) Merge (fa7f743) Diff
  size 17.1 kB 17.1 kB +27 B (+0.2%)
  size-with-ext-deps 35.6 kB 35.6 kB +27 B (+0.1%)

Test Logs

https://storage.googleapis.com/firebase-sdk-metric-reports/0oUZK6ZrVv.html

docs-devsite/vertexai-preview.generationconfig.md

docs-devsite/vertexai-preview.md

rachelsaunders · 2024-09-17T18:32:05Z

docs-devsite/vertexai-preview.md

+|  [IntegerSchema](./vertexai-preview.integerschema.md#integerschema_class) | Schema class for "integer" types. |
+|  [NumberSchema](./vertexai-preview.numberschema.md#numberschema_class) | Schema class for "number" types. |
+|  [ObjectSchema](./vertexai-preview.objectschema.md#objectschema_class) | Schema class for "object" types. The <code>properties</code> param must be a map of Schema. |
+|  [Schema](./vertexai-preview.schema.md#schema_class) | Parent class encompassing all Schema types, with static methods that allow building specific Schema types. This class can be converted with JSON.stringify() into a JSON string accepted by Vertex REST endpoints. (This string conversion is automatically done when calling SDK methods.) |


Vertex -> Vertex AI

(comment applies to several other instances, even in other files)

I can't seem to find the corresponding new file in the new set of files?

I think the missing files should be back now.

rachelsaunders · 2024-09-17T18:33:31Z

docs-devsite/vertexai-preview.md

 |  [HarmBlockMethod](./vertexai-preview.md#harmblockmethod) |  |
 |  [HarmBlockThreshold](./vertexai-preview.md#harmblockthreshold) | Threshold above which a prompt or candidate will be blocked. |
 |  [HarmCategory](./vertexai-preview.md#harmcategory) | Harm categories that would cause prompts or candidates to be blocked. |
 |  [HarmProbability](./vertexai-preview.md#harmprobability) | Probability that a prompt or candidate matches a harm category. |
 |  [HarmSeverity](./vertexai-preview.md#harmseverity) | Harm severity levels. |
+|  [SchemaType](./vertexai-preview.md#schematype) | Contains the list of OpenAPI data types as defined by https://swagger.io/docs/specification/data-models/data-types/ |


NOT BLOCKING

Usually, we try to make all URLs into hyperlinks rather than having the actual URL exposed.

(comment applies to several other instances, even in other files)

I can't seem to find the corresponding new file in the new set of files?

rachelsaunders · 2024-09-17T18:34:38Z

docs-devsite/vertexai-preview.md

+|  [SchemaInterface](./vertexai-preview.schemainterface.md#schemainterface_interface) | Interface for Schema class. |
+|  [SchemaParams](./vertexai-preview.schemaparams.md#schemaparams_interface) | User-facing params passed to specific Schema static methods. |
+|  [SchemaRequest](./vertexai-preview.schemarequest.md#schemarequest_interface) | Final format for Schema params passed to backend requests. |
+|  [SchemaShared](./vertexai-preview.schemashared.md#schemashared_interface) | Basic <code>Schema</code> properties shared across several Schema-related types. |


Why is Schema tagged as code here, but not anywhere else?

FWIW - I would prolly recommend tagging it almost everywhere as code. And ObjectSchema and StringSchema, too.

Can actually make them links, so did so.

I can't seem to find the corresponding new file in the new set of files?

docs-devsite/vertexai-preview.schema.md

rachelsaunders · 2024-09-17T18:48:03Z

docs-devsite/vertexai-preview.schema.md

+|  [number(numberParams)](./vertexai-preview.schema.md#schemanumber) | <code>static</code> |  |
+|  [object(objectParams)](./vertexai-preview.schema.md#schemaobject) | <code>static</code> |  |
+|  [string(stringParams)](./vertexai-preview.schema.md#schemastring) | <code>static</code> |  |
+|  [toJSON()](./vertexai-preview.schema.md#schematojson) |  | Defines how this Schema should be serialized as JSON. See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global\_Objects/JSON/stringify\#tojson\_behavior |


another exposed URL that should be a hyperlink

Was it intentional to remove toJSON() here? Maybe I'm missing it, but it doesn't seem to be in the newly generated file?

docs-devsite/vertexai.schema.md

Yes, it doesn't need to be publicly exposed, it's for internal use.

docs-devsite/vertexai-preview.schemaparams.md

changeset-bot · 2024-09-19T16:56:44Z

⚠️ No Changeset found

Latest commit: 9af2001

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

hsubox76

Addressed comments. Some of the changes have added some source files to this PR, that are the source of the changes. You don't have to review them, you can just look at the markdown files.

DellaBitta

Is it a problem that docs-devsite/_toc.yaml was removed?

rachelsaunders · 2024-09-28T09:08:21Z

docs-devsite/vertexai.generationconfig.md


 <b>Signature:</b>

 ```typescript
 responseMimeType?: string;
 ```

+## GenerationConfig.responseSchema
+
+Output response schema of the generated candidate text. This value can be a class generated with a [Schema](./vertexai-preview.schema.md#schema_class) static method like `Schema.string()` or `Schema.object()` or it can be a plain JS object matching the [SchemaRequest](./vertexai-preview.schemarequest.md#schemarequest_interface) interface. <br/>Note: This only applies when the specified `responseMIMEType` supports a schema; currently this is limited to `application/json`<!-- -->.


Shouldn't responseSchema also support the MIME type of text/x.enum?

https://cloud.google.com/vertex-ai/generative-ai/docs/multimodal/control-generated-output#considerations

I guess so. Added. I don't really know anything about it other than what's in that page so I just put the type in there and didn't add any explanation. I originally pulled this comment off the proto. https://source.corp.google.com/piper///depot/google3/google/cloud/aiplatform/master/content.proto;l=269?q=generationconfig&ss=piper%2FGoogle%2FPiper:google3%2Fgoogle%2Fcloud%2Faiplatform%2Fmaster%2F

I'm not sure what I'm supposed to use for the source of truth.

rachelsaunders · 2024-09-28T09:18:04Z

docs-devsite/vertexai.generationconfig.md


 <b>Signature:</b>

 ```typescript
 responseMimeType?: string;
 ```

+## GenerationConfig.responseSchema
+
+Output response schema of the generated candidate text. This value can be a class generated with a [Schema](./vertexai-preview.schema.md#schema_class) static method like `Schema.string()` or `Schema.object()` or it can be a plain JS object matching the [SchemaRequest](./vertexai-preview.schemarequest.md#schemarequest_interface) interface. <br/>Note: This only applies when the specified `responseMIMEType` supports a schema; currently this is limited to `application/json`<!-- -->.


NOT BLOCKING

Schema and SchemaRequest

Both should be tagged as code in the source code. Pls look throughout the source code for other instances.

Anytime that you're referring to a specific component (method / field / enum / etc. name, file names, input / output value, etc.), then tag it as code.

One very generalized way to think about it to decide if something should be tagged as code: "Would I want this translated into German, Korean, etc.?" Note that our ref docs aren't translated, but this way of thinking helps you decide about appropriate tagging :-)

I'm assuming by "tag as code" you mean to make it so it ends up in the markdown within <code> tags? This was pretty tricky, we normally do it with backticks but you can't do it on links so you normally choose between either having a link or having code tags. I think I found a way to do it although it's a little fragile. I did a search/replace on all @links in the package.

rachelsaunders · 2024-09-28T09:28:39Z

docs-devsite/vertexai-preview.md

 |  [HarmBlockMethod](./vertexai-preview.md#harmblockmethod) |  |
 |  [HarmBlockThreshold](./vertexai-preview.md#harmblockthreshold) | Threshold above which a prompt or candidate will be blocked. |
 |  [HarmCategory](./vertexai-preview.md#harmcategory) | Harm categories that would cause prompts or candidates to be blocked. |
 |  [HarmProbability](./vertexai-preview.md#harmprobability) | Probability that a prompt or candidate matches a harm category. |
 |  [HarmSeverity](./vertexai-preview.md#harmseverity) | Harm severity levels. |
+|  [SchemaType](./vertexai-preview.md#schematype) | Contains the list of OpenAPI data types as defined by https://swagger.io/docs/specification/data-models/data-types/ |


I can't seem to find the corresponding new file in the new set of files?

rachelsaunders · 2024-09-28T09:32:09Z

docs-devsite/vertexai-preview.md

+|  [SchemaInterface](./vertexai-preview.schemainterface.md#schemainterface_interface) | Interface for Schema class. |
+|  [SchemaParams](./vertexai-preview.schemaparams.md#schemaparams_interface) | User-facing params passed to specific Schema static methods. |
+|  [SchemaRequest](./vertexai-preview.schemarequest.md#schemarequest_interface) | Final format for Schema params passed to backend requests. |
+|  [SchemaShared](./vertexai-preview.schemashared.md#schemashared_interface) | Basic <code>Schema</code> properties shared across several Schema-related types. |


I can't seem to find the corresponding new file in the new set of files?

rachelsaunders · 2024-09-28T09:37:54Z

docs-devsite/vertexai.schemashared.md

+|  [format](./vertexai.schemashared.md#schemasharedformat) | string | Optional. The format of the property. |
+|  [items](./vertexai.schemashared.md#schemashareditems) | T | Optional. The items of the property. |
+|  [nullable](./vertexai.schemashared.md#schemasharednullable) | boolean | Optional. Whether the property is nullable. |
+|  [properties](./vertexai.schemashared.md#schemasharedproperties) | { \[k: string\]: T; } | Optional. Map of Schemas. |


NOT BLOCKING

This should probably be this?

Map of Schema objects.

rachelsaunders · 2024-09-28T09:38:36Z

docs-devsite/vertexai-preview.md

+|  [IntegerSchema](./vertexai-preview.integerschema.md#integerschema_class) | Schema class for "integer" types. |
+|  [NumberSchema](./vertexai-preview.numberschema.md#numberschema_class) | Schema class for "number" types. |
+|  [ObjectSchema](./vertexai-preview.objectschema.md#objectschema_class) | Schema class for "object" types. The <code>properties</code> param must be a map of Schema. |
+|  [Schema](./vertexai-preview.schema.md#schema_class) | Parent class encompassing all Schema types, with static methods that allow building specific Schema types. This class can be converted with JSON.stringify() into a JSON string accepted by Vertex REST endpoints. (This string conversion is automatically done when calling SDK methods.) |


I can't seem to find the corresponding new file in the new set of files?

rachelsaunders · 2024-09-28T09:42:23Z

docs-devsite/vertexai-preview.schema.md

+|  [number(numberParams)](./vertexai-preview.schema.md#schemanumber) | <code>static</code> |  |
+|  [object(objectParams)](./vertexai-preview.schema.md#schemaobject) | <code>static</code> |  |
+|  [string(stringParams)](./vertexai-preview.schema.md#schemastring) | <code>static</code> |  |
+|  [toJSON()](./vertexai-preview.schema.md#schematojson) |  | Defines how this Schema should be serialized as JSON. See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global\_Objects/JSON/stringify\#tojson\_behavior |


Was it intentional to remove toJSON() here? Maybe I'm missing it, but it doesn't seem to be in the newly generated file?

docs-devsite/vertexai.schema.md

hsubox76 marked this pull request as ready for review September 17, 2024 18:24

hsubox76 requested a review from a team as a code owner September 17, 2024 18:24

rachelsaunders requested changes Sep 17, 2024

View reviewed changes

hsubox76 requested a review from a team as a code owner September 19, 2024 16:56

hsubox76 commented Sep 19, 2024

View reviewed changes

DellaBitta reviewed Sep 20, 2024

View reviewed changes

hsubox76 force-pushed the ch-schema-docs branch 2 times, most recently from e6195cd to 145e5d8 Compare September 23, 2024 17:30

hsubox76 changed the title ~~Generate Schema docs~~ [Vertex GA] Generate Schema docs Sep 23, 2024

hsubox76 added the api: vertexai label Sep 23, 2024

hsubox76 added this to the Vertex GA milestone Sep 23, 2024

hsubox76 changed the base branch from ch-schema to v11 September 24, 2024 17:25

hsubox76 force-pushed the ch-schema-docs branch from 36f0008 to 0b8615d Compare September 25, 2024 16:00

hsubox76 changed the base branch from v11 to ch-docs-rename-base September 25, 2024 16:17

hsubox76 force-pushed the ch-schema-docs branch from e3258c4 to ba61bce Compare September 25, 2024 16:24

hsubox76 changed the title ~~[Vertex GA] Generate Schema docs~~ [Vertex GA] Regenerate docs after Vertex GA changes Sep 25, 2024

rachelsaunders requested changes Sep 28, 2024

View reviewed changes

hsubox76 force-pushed the ch-schema-docs branch from 8b1833c to ff3aaf6 Compare September 30, 2024 20:25

dlarocque and others added 8 commits September 30, 2024 13:26

Emit a module package file for functions ESM builds (#8517)

6a7e6ac

Update API_NOT_ENABLED error for Vertex (#8549)

7f7dd65

fill out Schema builder

0cd9f37

refine design

39ebdfb

Update doc comments

34baa7b

More fixes to doc comments

1f59dce

Fixes based on testing

6212c28

fix error class

bf1279a

hsubox76 and others added 13 commits September 30, 2024 13:26

Allow raw json in responseSchema

40d931f

set SchemaShared to public

1ee080b

fix docs

d84e51f

revert docs

e3622e7

remove other added docs

6d76f93

restore toc

239fb99

rerun docgen

d01abc3

redo docs

2b34c04

rename to vertexai

6858e70

remove old api preview

c577be4

fix some merge issues

7b44f66

Update API reports

67c5c36

Address some PR comments

9af2001

hsubox76 force-pushed the ch-schema-docs branch from ff3aaf6 to 9af2001 Compare September 30, 2024 20:26

[Vertex GA] Regenerate docs after Vertex GA changes #8505

Are you sure you want to change the base?

[Vertex GA] Regenerate docs after Vertex GA changes #8505

Conversation

hsubox76 commented Sep 17, 2024 • edited Loading

google-oss-bot commented Sep 17, 2024 • edited Loading

Size Report 1

Affected Products

@firebase/vertexai

firebase

Test Logs

google-oss-bot commented Sep 17, 2024 • edited Loading

Size Analysis Report 1

Affected Products

@firebase/vertexai

ChatSession

GenerativeModel

getGenerativeModel

Test Logs

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

changeset-bot bot commented Sep 19, 2024 • edited Loading

⚠️ No Changeset found

hsubox76 left a comment

Choose a reason for hiding this comment

DellaBitta left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

hsubox76 commented Sep 17, 2024 •

edited

Loading

google-oss-bot commented Sep 17, 2024 •

edited

Loading

Size Report ¹

`@firebase/vertexai`

`firebase`

google-oss-bot commented Sep 17, 2024 •

edited

Loading

Size Analysis Report ¹

`@firebase/vertexai`

`ChatSession`

`GenerativeModel`

`getGenerativeModel`

changeset-bot bot commented Sep 19, 2024 •

edited

Loading