diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
new file mode 100644
index 0000000..0b86843
--- /dev/null
+++ b/.github/CONTRIBUTING.md
@@ -0,0 +1,37 @@
+# Contributing
+
+Thank you for taking the time to contribute!
+
+## Techstack
+
+Gemini AI is built with the following tools. Ensure you have `bun` [installed](https://bun.sh/).
+
+- [**Bun**](https://bun.sh/) as the package manager
+- [**Biome**](https://biomejs.dev/) as the linter and formatter
+- [**tsup**](https://tsup.egoist.dev/) as the build tool
+
+Follow the [Github flow](https://docs.github.com/en/get-started/using-github/github-flow) to clone the repo and create a branch.
+
+It is recommended to install Biome integration with your IDE to format your code.
+
+## Scripts
+
+### `bun run build`
+
+Use this to build your project, should you need to test it locally.
+
+It uses `tsup` under the hood.
+
+### `bun run test`
+
+Use this to test your project with existing unit tests. These tests will also be ran on your PR, so ensure they are passing!
+
+It uses `vitest` under the hood.
+
+You can also use `bun run coverage` to check coverage of your tests.
+
+### `bun run check`
+
+Use this to check if your code follows our formatting standards.
+
+It uses Biome under the hood.
diff --git a/.github/README.md b/.github/README.md
index 1c09379..d04ee1d 100644
--- a/.github/README.md
+++ b/.github/README.md
@@ -1,41 +1,79 @@
-
-
-
-
-
-
+
-> [!NOTE]
-> With the release of Gemini AI 1.1, there is now **streaming support**! Check it out [here](#streaming).
-
## Features
-- 🌎 [**Multimodal**](#auto-model-selection): Interact with text and images—Native to the model.
+- 🌎 [**Multimodal**](#auto-model-selection): Interact with images, videos, audio, and more, built into the model.
- 🌐 [**Contextual Conversations**](#geminicreatechat): Chat with Gemini, built in.
-- 🧪 [**Parameter**](#method-patterns): Easily modify `temperature`, `topP`, and more
+- 🧪 [**Simple Parameters**](#method-patterns): Easily modify `temperature`, `topP`, and more
- ⛓️ [**Streaming**](#streaming): Get AI output the second it's available.
+- 🔒 [**Typesafe**](#types): Types built in. Gemini AI is written with TypeScript
+
+## Why Gemini AI
+
+> Why should I use this, instead of Google's [own API](https://www.npmjs.com/package/@google/generative-ai)?
+
+It's all about simplicity. Gemini AI allows you to make requests to Gemini at just about a quarter of the code necessary with Google's API.
+
+
+Don't believe me? Take a look.
+
+
+
+Google's own API (CommonJS):
+
+```javascript
+const { GoogleGenerativeAI } = require("@google/generative-ai");
+
+const genAI = new GoogleGenerativeAI(API_KEY);
+
+async function run() {
+ const model = genAI.getGenerativeModel({ model: "gemini-1.5-pro-latest" });
+
+ const prompt = "Hi!";
+
+ const result = await model.generateContent(prompt);
+ const response = await result.response;
+ const text = response.text();
+ console.log(text);
+}
+
+run();
+```
+
+Gemini AI (ES6 Modules):
+
+```javascript
+import Gemini from "gemini-ai";
+
+const gemini = new Gemini(API_KEY);
+console.log(await gemini.ask("Hi!"));
+```
+
+That's nearly 4 times less code!
+
+
-## Highlights
+And there's no sacrifices either. Gemini AI uses Google's REST API under the hood, so you get simplicity without compromise.
-Gemini AI v1.0 compared to Google's [own API](https://www.npmjs.com/package/@google/generative-ai)
+And, there's also more!
-- ⚡ [**Native REST API**](#inititalization): Have simplicity without compromises
-- 🚀 [**Easy**](#feature-highlight-auto-model-selection): Auto model selection based on context
-- 🎯 [**Concise**](#why-gemini-ai): _**4x**_ less code needed
+- 📝 [**Optimized File Uploads**](#optimized-file-uploads): Automatically uses Google's File API when necessary
+- 📁 [**Automatic File Type Detection**](#optimized-file-uploads): Gemini AI will detect MIME types of files automatically
+- 🧩 [**Automatic Request Creation**](): Auto-formats your requests—So you don't have to.
## Table of Contents
@@ -54,16 +92,16 @@ Gemini AI v1.0 compared to Google's [own API](https://www.npmjs.com/package/@goo
## Getting an API Key
-1. Go to [Google Makersuite](https://makersuite.google.com)
-2. Click "Get API key" at the top, and follow the steps to get your key
+1. Go to [Google AI Studio's API keys tab](https://aistudio.google.com/app/apikey)
+2. Follow the steps to get an API key
3. Copy this key, and use it below when `API_KEY` is mentioned.
-> [!CAUTION]
+> [!WARNING]
> Do not share this key with other people! It is recommended to store it in a `.env` file.
## Quickstart
-Make a text request (`gemini-pro`):
+Make a text request:
```javascript
import Gemini from "gemini-ai";
@@ -73,7 +111,7 @@ const gemini = new Gemini(API_KEY);
console.log(await gemini.ask("Hi!"));
```
-Make a streaming text request (`gemini-pro`):
+Make a streaming text request:
```javascript
import Gemini from "gemini-ai";
@@ -85,10 +123,10 @@ gemini.ask("Hi!", {
});
```
-Chat with Gemini (`gemini-pro`):
+Chat with Gemini:
```javascript
-import fs from "fs";
+import Gemini from "gemini-ai";
const gemini = new Gemini(API_KEY);
const chat = gemini.createChat();
@@ -100,7 +138,7 @@ console.log(await chat.ask("What's the last thing I said?"));
### Other useful features
-Make a text request with images (gemini-pro-vision):
+Make a text request with images:
```javascript
@@ -110,16 +148,14 @@ import Gemini from "gemini-ai";
const gemini = new Gemini(API_KEY);
console.log(
- gemini.ask("What's this show?", {
- data: [fs.readFileSync("./test.png")],
- })
+ await gemini.ask(["What do you see?", fs.readFileSync("./cat.png")])
);
```
-Make a text request with custom parameters (gemini-pro):
+Make a text request with custom parameters:
```javascript
@@ -128,10 +164,9 @@ import Gemini from "gemini-ai";
const gemini = new Gemini(API_KEY);
console.log(
- gemini.ask("Hello!", {
+ await gemini.ask("Hello!", {
temperature: 0.5,
topP: 1,
- topK: 10,
})
);
```
@@ -139,7 +174,7 @@ console.log(
-Embed Text (`embedding-001`):
+Embed text:
```javascript
@@ -147,17 +182,13 @@ import fs from "fs";
const gemini = new Gemini(API_KEY);
-gemini.embed("Hi!");
+console.log(await gemini.embed("Hi!"));
```
## Special Features
-### Auto Model Selection
-
-Google has released two models this time for Gemini—`gemini-pro`, and `gemini-pro-vision`. The former is text-specific, while the latter is for multimodal use. Gemini AI has been designed so that it will automatically select which model it will use!
-
### Streaming
Here's a quick demo:
@@ -176,9 +207,25 @@ Let's walk through what this code is doing. Like always, we first initialize `Ge
Note that this automatically cuts to the `streamContentGenerate` command... you don't have to worry about that!
-> [!NOTE]
+> [!TIP]
> Realize that you don't need to call `ask` async if you're handling stream management on your own. If you want to tap the final answer, it still is returned by the method, and you call it async as normal.
+### Types
+
+Gemini AI v2 is completely written in TypeScript, which means that all parameters, and more importantly configuration, have type hints.
+
+Furthermore, return types are also conditional based on what `format` you place in the configuration to guarentee great DX.
+
+### Optimized File Uploads
+
+Google requires large files to be sent through their dedicated File API, instead of being included directly in the `POST` request.
+
+With Gemini AI v2, large files like videos and audio will automatically be detected and sent through the File API, while smaller images are still included inline—without you having to worry about any of that going on.
+
+This ensures the fastest file upload experience, while ensuring all your files are safely included.
+
+Gemini also automatically detects the MIME type of your file to pass to the server, so you don't need to worry abotu it.
+
### Proxy Support
Use a proxy when fetching from Gemini. To keep package size down and adhere to the [SRP](https://en.wikipedia.org/wiki/Single_responsibility_principle), the actual proxy handling is delegated to the [undici library](https://undici.nodejs.org/#/).
@@ -194,12 +241,12 @@ npm i undici
Initialize it with Gemini AI:
```javascript
-import { ProxyAgent } from 'undici'
-import Gemini from 'gemini-ai'
+import { ProxyAgent } from "undici";
+import Gemini from "gemini-ai";
let gemini = new Gemini(API_KEY, {
- dispatcher: new ProxyAgent(PROXY_URL)
-})
+ dispatcher: new ProxyAgent(PROXY_URL),
+});
```
And use as normal!
@@ -232,31 +279,92 @@ await gemini.ask("Hi!", {
// Config
temperature: 0.5,
topP: 1,
- topK: 10,
});
```
-> [!NOTE]
-> All methods are async! This means you should call them something like this: `await gemini.ask(...)`
+> [!TIP]
+> All methods (_except_ `Gemini.createChat()`) are async! This means you should call them something like this: `await gemini.ask(...)`
+
+#### JSON Output
+
+You have the option to set format to `Gemini.JSON`
+
+```javascript
+await gemini.ask("Hi!", {
+ format: Gemini.JSON,
+});
+```
+
+This gives you the full response from Gemini's REST API.
Note that the output to `Gemini.JSON` varies depending on the model and command, and is not documented here in detail due to the fact that it is unnecessary to use in most scenarios. You can find more information about the REST API's raw output [here](https://ai.google.dev/tutorials/rest_quickstart).
+If you are using typescript, you get type annotations for all the responses, so autocomplete away.
+
### `Gemini.ask()`
This method uses the `generateContent` command to get Gemini's response to your input.
-Config available:
-| Field Name | Description | Default Value |
-| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
-| `format` | Whether to return the detailed, raw JSON output. Typically not recommended, unless you are an expert. Can either be `Gemini.JSON` or `Gemini.TEXT` | `Gemini.TEXT` |
-| `topP` | See [Google's parameter explanations](https://cloud.google.com/vertex-ai/docs/generative-ai/start/quickstarts/api-quickstart#parameter_definitions) | `0.8` |
-| `topK` | See [Google's parameter explanations](https://cloud.google.com/vertex-ai/docs/generative-ai/start/quickstarts/api-quickstart#parameter_definitions) | `10` |
-| `temperature` | See [Google's parameter explanations](https://cloud.google.com/vertex-ai/docs/generative-ai/start/quickstarts/api-quickstart#parameter_definitions) | `1` |
-| `model` | Which model to use. Can be any model Google has available, but certain features are not available on some models. Currently: `gemini-pro` and `gemini-pro-vision` | Automatic based on Context |
-| `maxOutputTokens` | Max tokens to output | `800` |
-| `messages` | Array of `[userInput, modelOutput]` pairs to show how the bot is supposed to behave | `[]` |
-| `data` | An array of `Buffer`s to input to the model. Automatically toggles model to `gemini-pro-vision` | `[]` |
-| `stream` | A function that is called with every new chunk of JSON or Text (depending on the format) that the model receives. [Learn more](#feature-highlight-streaming)| `undefined` |
+#### Uploading Media
+
+The first parameter of the `ask()` method can take in 3 different forms:
+
+##### String Form:
+
+This is simply a text query to Gemini.
+
+_Example:_
+
+```javascript
+await gemini.ask("Hi!");
+```
+
+##### Array Form:
+
+In this array, which represents ordered "parts", you can put strings, or Buffers (these are what you get directly from `fs.readFileSync()`!). These will be fed, in order to Gemini.
+
+Gemini accepts most major file formats, so you shouldn't have to worry about what format you give it. However, check out a [comprehensive list here](https://ai.google.dev/gemini-api/docs/prompting_with_media?lang=javascript#supported_file_formats).
+
+There's a whole ton of optimizations under the hood for file uploads too, but you don't have to worry about them! [Learn more here...](#optimized-file-uploads)
+
+_Example:_
+
+```javascript
+import fs from "fs";
+
+await gemini.ask([
+ "Between these two cookies, which one appears to be home-made, and which one looks store-bought? Cookie 1:",
+ fs.readFileSync("./cookie1.png"),
+ "Cookie 2",
+ fs.readFileSync("./cookie2.png"),
+]);
+```
+
+> [!NOTE]
+> that you can also place buffers in the `data` field in the config (this is the v1 method, but it still works). These buffers will be placed, in order, directly after the content in the main message.
+
+##### Message Form:
+
+This is the raw message format. It is not meant to be used directly, but can be useful when needing raw control over file uploads, and it is also used internally by the `Chat` class.
+
+Please check `src/types.ts` for more information about what is accepted in the `Message` field.
+
+#### Config Available:
+
+> [!NOTE]
+> These are Google REST API defaults.
+
+| Field Name | Description | Default Value |
+| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
+| `format` | Whether to return the detailed, raw JSON output. Typically not recommended, unless you are an expert. Can either be `Gemini.JSON` or `Gemini.TEXT` | `Gemini.TEXT` |
+| `topP` | See [Google's parameter explanations](https://cloud.google.com/vertex-ai/docs/generative-ai/start/quickstarts/api-quickstart#parameter_definitions) | `0.94` |
+| `topK` | See [Google's parameter explanations](https://cloud.google.com/vertex-ai/docs/generative-ai/start/quickstarts/api-quickstart#parameter_definitions). Note that this field is **not** available on v1.5 models. | `32` |
+| `temperature` | See [Google's parameter explanations](https://cloud.google.com/vertex-ai/docs/generative-ai/start/quickstarts/api-quickstart#parameter_definitions) | `1` |
+| `model` | `gemini-1.5-flash-latest` |
+| `maxOutputTokens` | Max tokens to output | `2048` |
+| `messages` | Array of `[userInput, modelOutput]` pairs to show how the bot is supposed to behave | `[]` |
+| `data` | An array of `Buffer`s to input to the model. It is recommended that you [directly pass data through the message in v2](#uploading-media). | `[]` |
+| `stream` | A function that is called with every new chunk of JSON or Text (depending on the format) that the model receives. [Learn more](#feature-highlight-streaming) | `undefined` |
Example Usage:
@@ -269,7 +377,6 @@ console.log(
await gemini.ask("Hello!", {
temperature: 0.5,
topP: 1,
- topK: 10,
})
);
```
@@ -314,22 +421,19 @@ console.log(await gemini.embed("Hello!"));
### `Gemini.createChat()`
-`Gemini.createChat()` is a unique method. For one, it isn't asynchronously called. Additionally, it returns a brand new `Chat` object. The `Chat` object only has one method, which is `Chat.ask()`, which has the _exact same syntax_ as the `Gemini.ask()` method, documented [above](#geminiask). The only small difference is that most parameters are passed into the `Chat` through `createChat()`, and cannot be overriden by the `ask()` method. The only parameters that can be overridden is `format`, `stream`, and `data` (**As of 12/13/2023, `data` is not supported yet**).
-
-> [!IMPORTANT]
-> Google has not yet allowed the use of the `gemini-pro-vision` model in continued chats yet—The feature is already implemented, to a certain degree, but cannot be used due to Google's API limitations.
+`Gemini.createChat()` is a unique method. For one, it isn't asynchronously called. Additionally, it returns a brand new `Chat` object. The `Chat` object only has one method, which is `Chat.ask()`, which has the _exact same syntax_ as the `Gemini.ask()` method, documented [above](#geminiask). The only small difference is that most parameters are passed into the `Chat` through `createChat()`, and cannot be overriden by the `ask()` method. The only parameters that can be overridden is `format`, `stream`, and `data`.
All important data in the `Chat` object is stored in the `Chat.messages` variable, and can be used to create a new `Chat` that "continues" the conversation, as will be demoed in the example usage section.
Config available for `createChat`:
| Field Name | Description | Default Value |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
-| `topP` | See [Google's parameter explanations](https://cloud.google.com/vertex-ai/docs/generative-ai/start/quickstarts/api-quickstart#parameter_definitions) | `0.8` |
-| `topK` | See [Google's parameter explanations](https://cloud.google.com/vertex-ai/docs/generative-ai/start/quickstarts/api-quickstart#parameter_definitions) | `10` |
+| `topP` | See [Google's parameter explanations](https://cloud.google.com/vertex-ai/docs/generative-ai/start/quickstarts/api-quickstart#parameter_definitions) | `0.94` |
+| `topK` | See [Google's parameter explanations](https://cloud.google.com/vertex-ai/docs/generative-ai/start/quickstarts/api-quickstart#parameter_definitions). Note that this field is **not** available on v1.5 models. | `10` |
| `temperature` | See [Google's parameter explanations](https://cloud.google.com/vertex-ai/docs/generative-ai/start/quickstarts/api-quickstart#parameter_definitions) | `1` |
-| `model` | Which model to use. Can be any model Google has available, but certain features are not available on some models. Currently: `gemini-pro` and `gemini-pro-vision` | Automatic based on Context |
-| `maxOutputTokens` | Max tokens to output | `800` |
-| `messages` | Array of `[userInput, modelOutput]` pairs to show how the bot is supposed to behave | `[]` |
+| `model` | `gemini-1.5-flash-latest` |
+| `maxOutputTokens` | Max tokens to output | `2048` |
+| `messages` | Array of `[userInput, modelOutput]` pairs to show how the bot is supposed to behave (or to continue a conversation) | `[]` |
Example Usage:
@@ -343,6 +447,8 @@ const gemini = new Gemini(API_KEY);
const chat = gemini.createChat();
console.log(await chat.ask("Hi!"));
+
+// Now, you can start a conversation
console.log(await chat.ask("What's the last thing I said?"));
```
@@ -357,6 +463,8 @@ const chat = gemini.createChat();
console.log(await chat.ask("Hi!"));
+// Creating a new chat, with existing messages
+
const newChat = gemini.createChat({
messages: chat.messages,
});
@@ -366,49 +474,87 @@ console.log(await newChat.ask("What's the last thing I said?"));
## FAQ
-### Why Gemini AI?
+### What's the difference between `data` and directly passing buffers in the message?
-Well, simply put, it makes using Gemini just that much easier... see the code necessary to make a request using Google's own API, compared to Gemini AI:
+`data` was the old way to pass Media data. It is now not recommended, but kept for backwards compatability. The new method is to simply pass an array of strings/buffers into the first parameter of `ask()`. The major benefit is now you can include strings between buffers, which you couldn't do before. Here's a quick demo of how to migrate:
-
-See the comparison
-
+With `data`:
-Google's own API (CommonJS):
+```javascript
+import fs from "fs";
+
+await gemini.ask(
+ "Between these two cookies, which one appears to be home-made, and which one looks store-bought?",
+ {
+ data: [fs.readFileSync("./cookie1.png"), fs.readFileSync("./cookie2.png")],
+ }
+);
+```
+
+New Version:
```javascript
-const { GoogleGenerativeAI } = require("@google/generative-ai");
+import fs from "fs";
-const genAI = new GoogleGenerativeAI(API_KEY);
+await gemini.ask([
+ "Between these two cookies, which one appears to be home-made, and which one looks store-bought?",
+ fs.readFileSync("./cookie1.png"),
+ fs.readFileSync("./cookie2.png"),
+]);
+```
-async function run() {
- const model = genAI.getGenerativeModel({ model: "gemini-pro" });
+Learn more in the [dedicated section](#uploading-media).
- const prompt = "Hi!";
+### What do I need to do for v2?
- const result = await model.generateContent(prompt);
- const response = await result.response;
- const text = response.text();
- console.log(text);
-}
+> Does everything still work?
-run();
-```
+Yes! Gemini AI v2 should completely be backward-compatible. Most changes are under-the-hood, so your DX should be much smoother, [especially for TS developers](#types)!
-Gemini AI (ES6 Modules):
+The only thing that you can consider changing is using the new array message format instead of the old buffer format. See the [dedicated question](#whats-the-difference-between-data-and-directly-passing-buffers-in-the-message) to learn more.
+
+### What is the default model?
+
+> And, by extension, why is it the default model?
+
+By default, Gemini AI uses `gemini-1.5-flash-latest`, Google's leading efficiency-based model. The reason that this is the default model is because of two main reasons regarding DX:
+
+1. 📈 **Higher Rate Limits**: Gemini 1.5 Pro is limited to 2 requests per minute, versus the 15 for Flash, so we choose the one with the higher rate limit, which is especially useful for development.
+2. ⚡ **Faster Response Time**: Gemini 1.5 Pro is a significant amount slower, so we use the faster model by default.
+
+But, of course, should you need to change the model, it's as easy as passing it into the configuration of your request. For example:
```javascript
import Gemini from "gemini-ai";
const gemini = new Gemini(API_KEY);
-console.log(await gemini.ask("Hi!"));
+
+console.log(
+ await gemini.ask("Hello!", {
+ model: "gemini-1.5-pro-latest",
+ })
+);
```
-That's nearly 4 times less code!
+### Changing the API Version
-
+> What if I want to use a deprecated command?
+
+When initializing `Gemini`, you can pass in an API version. This feature mainly exists to futureproof, as the current recommended API version (and the one used) is `v1beta`. Note that some modern models (including the default Gemini 1.5 Flash) may not work on other API versions.
+
+Here's how you can change it to, say, v1:
+
+```javascript
+import Gemini from "gemini-ai";
+
+const gemini = new Gemini(API_KEY, {
+ apiVersion: "v1",
+});
+```
+
+### How to Polyfill Fetch
-### I'm in a browser environment! What do I do?
+> I'm in a browser environment! What do I do?
Everything is optimized so it works for both browsers and Node.js—Files are passed as Buffers, so you decide how to get them, and adding a fetch polyfill is as easy as:
diff --git a/.gitignore b/.gitignore
index f05f220..65bf0c0 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,4 @@
/node_modules
.DS_Store
-/coverage
\ No newline at end of file
+/coverage
+/dist
\ No newline at end of file
diff --git a/.npmignore b/.npmignore
index 535b9fd..338c4f2 100644
--- a/.npmignore
+++ b/.npmignore
@@ -2,4 +2,8 @@
/coverage
/.github
/test
-/bun.lockb
\ No newline at end of file
+/bun.lockb
+/src
+tsconfig.json
+tsup.config.ts
+biome.json
diff --git a/README.md b/README.md
index a2ddf21..26f8a13 100644
--- a/README.md
+++ b/README.md
@@ -5,10 +5,10 @@
-
+
-
-
+
+
-
-> [!NOTE]
-> With the release of Gemini AI 1.1, there is now **streaming support**! Check it out [here](#streaming).
-
## Features
-- 🌎 [**Multimodal**](#auto-model-selection): Interact with text and images—Native to the model.
+- 🌎 [**Multimodal**](#auto-model-selection): Interact with images, videos, audio, and more, built into the model.
- 🌐 [**Contextual Conversations**](#geminicreatechat): Chat with Gemini, built in.
-- 🧪 [**Parameter**](#method-patterns): Easily modify `temperature`, `topP`, and more
+- 🧪 [**Simple Parameters**](#method-patterns): Easily modify `temperature`, `topP`, and more
- ⛓️ [**Streaming**](#streaming): Get AI output the second it's available.
+- 🔒 [**Typesafe**](#types): Types built in. Gemini AI is written with TypeScript
+
+## Why Gemini AI
+
+> Why should I use this, instead of Google's [own API](https://www.npmjs.com/package/@google/generative-ai)?
+
+It's all about simplicity. Gemini AI allows you to make requests to Gemini at just about a quarter of the code necessary with Google's API.
+
+
- 
+ 
-
- 
+
+ 