{"id":19947346,"url":"https://github.com/firstbatchxyz/firstbatch-sdk-ts","last_synced_at":"2025-05-03T17:33:47.575Z","repository":{"id":208472473,"uuid":"705597153","full_name":"firstbatchxyz/firstbatch-sdk-ts","owner":"firstbatchxyz","description":"TypeScript SDK for FirstBatch: Real-time Personalization using VectorDBs.","archived":false,"fork":false,"pushed_at":"2024-02-16T08:42:20.000Z","size":181,"stargazers_count":5,"open_issues_count":3,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-15T09:52:37.753Z","etag":null,"topics":["personalization","pinecone","sdk","typesense","vector-database","vectordb","weaviate"],"latest_commit_sha":null,"homepage":"https://firstbatch.xyz/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/firstbatchxyz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2023-10-16T10:22:48.000Z","updated_at":"2024-05-08T15:02:53.000Z","dependencies_parsed_at":"2024-01-29T09:01:31.492Z","dependency_job_id":null,"html_url":"https://github.com/firstbatchxyz/firstbatch-sdk-ts","commit_stats":null,"previous_names":["firstbatchxyz/firstbatch-sdk-ts"],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/firstbatchxyz%2Ffirstbatch-sdk-ts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/firstbatchxyz%2Ffirstbatch-sdk-ts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/firstbatchxyz%2Ffirstbatch-sdk-ts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/firstbatchxyz%2Ffirstbatch-sdk-ts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/firstbatchxyz","download_url":"https://codeload.github.com/firstbatchxyz/firstbatch-sdk-ts/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252227173,"owners_count":21714957,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["personalization","pinecone","sdk","typesense","vector-database","vectordb","weaviate"],"created_at":"2024-11-13T00:35:42.387Z","updated_at":"2025-05-03T17:33:47.015Z","avatar_url":"https://github.com/firstbatchxyz.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003c!-- \u003cimg src=\"https://raw.githubusercontent.com/firstbatchxyz/firstbatch-sdk-ts/master/logo.svg\" alt=\"logo\" width=\"142\"\u003e --\u003e\n  \u003cimg src=\"./logo.svg\" alt=\"logo\" width=\"142\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ch1 align=\"center\"\u003e\n    FirstBatch SDK\n  \u003c/h1\u003e\n  \u003cp align=\"center\"\u003e\n    \u003ci\u003eFirstBatch SDK provides an interface for integrating vector databases and powering personalized AI experiences in your application.\u003c/i\u003e\n  \u003c/p\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://opensource.org/licenses/MIT\" target=\"_blank\"\u003e\n        \u003cimg alt=\"License: MIT\" src=\"https://img.shields.io/badge/license-MIT-7CB9E8.svg\"\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://www.npmjs.com/package/firstbatch\" target=\"_blank\"\u003e\n        \u003cimg alt=\"NPM\" src=\"https://img.shields.io/npm/v/firstbatch?logo=npm\u0026color=CB3837\"\u003e\n    \u003c/a\u003e\n    \u003c!-- \u003ca href=\"./.github/workflows/test.yml\" target=\"_blank\"\u003e\n        \u003cimg alt=\"Workflow: Tests\" src=\"https://github.com/firstbatchxyz/firstbatch-sdk-ts/actions/workflows/test.yml/badge.svg?branch=master\"\u003e\n    \u003c/a\u003e --\u003e\n    \u003ca href=\"https://discord.gg/2wuU9ym6fq\" target=\"_blank\"\u003e\n        \u003cimg alt=\"Discord\" src=\"https://dcbadge.vercel.app/api/server/2wuU9ym6fq?style=flat\"\u003e\n    \u003c/a\u003e\n\u003c/p\u003e\n\n- [x] Seamlessly manage user sessions with persistent IDs or temporary sessions.\n- [x] Send signal actions like likes, clicks, etc. to update user embeddings in real-time.\n- [x] Fetch personalized batches of data tailored to each user's embeddings.\n- [x] Support for multiple vector database integrations: Pinecone, Weaviate, etc.\n- [x] Built-in algorithms for common personalization use cases.\n\nFor more information, see the [User Embedding Guide](https://firstbatch.gitbook.io/user-embeddings/) or the [SDK Documentation](https://firstbatch.gitbook.io/firstbatch-sdk/).\n\n## Installation\n\nInstall the package from NPM:\n\n```sh\nnpm install firstbatch  # npm\nyarn add firstbatch     # yarn\npnpm add firstbatch     # pnpm\n```\n\n## Usage\n\nFirstBatch SDK is used together with an existing vector store, where you register the vector store to our SDK and then create personalization sessions from it.\n\n### Adding a Client\n\nFirst, initialize a Vector Database of your choice; our SDK supports:\n\n- [x] [Pinecone](https://www.npmjs.com/package/@pinecone-database/pinecone)\n- [x] [Weaviate](https://www.npmjs.com/package/weaviate-ts-client)\n- [ ] [Typesense](https://www.npmjs.com/package/typesense) (work in progress)\n- [ ] [Supabase](https://www.npmjs.com/package/@supabase/supabase-js) (work in progress)\n\nLet us go over an example using Pinecone.\n\n```ts\nimport {Pinecone as PineconeClient} from '@pinecone-database/pinecone';\nimport {Pinecone, FirstBatch, Signals} from 'firstbatch';\n\n// create Pinecone client\nconst pinecone = new PineconeClient({apiKey: 'pinecone-api-key', environment: 'pinecone-env'});\nawait pinecone.describeIndex('index-name');\nconst index = pinecone.index('index-name');\n```\n\nThen, create a Vector Store with this index and pass it in the FirstBatch SDK.\n\n```ts\n// create SDK\nconst personalized = await FirstBatch.new('firstbatch-api-key');\n\n// add vector store to SDK\nconst vectorStore = new Pinecone(index);\nconst vdbid = 'pinecone-example-db';\nawait personalized.addVectorStore(vdbid, vectorStore);\n```\n\n### Personalization\n\nNow, we can create a session with an algorithm that suits our use-case, and provide personalization to our users.\n\n```ts\n// create a session\nconst session = personalized.session('ALGORITHM_NAME', vdbid);\n\n// make recommendations\nconst [ids, batch] = personalized.batch(session);\n```\n\nSuppose that the user has **liked** the **first content** from the `batch` above. We can provide personalization over this as follows:\n\n```ts\n// the user liked the first content of the previous batch\nconst userPick = ids[0];\n\n// signal this to the session\npersonalized.addSignal(sessionId, Signals.LIKE, userPick);\n```\n\nHere, `LIKE` signal is one of the many preset signals provided by our SDK. You can also define your own signals:\n\n```ts\nimport type {Signal} from 'firstbatch';\n\nconst mySignal: Signal = {label: 'SOME_USER_ACTION', weight: 0.5};\n```\n\n## Building\n\nInstall the dependencies:\n\n```bash\nbun install\n```\n\nThen, build everything with:\n\n```bash\nbun run build\nbun b # alternative\n```\n\n\u003e [!NOTE]\n\u003e\n\u003e If you get an error like \"expected content key ... to exist\" simply delete the `.parcel-cache` folder and build again.\n\n## Testing\n\nRun all tests via:\n\n```bash\nbun run test\nbun t # alternative\n```\n\nBun will look for `.env.test` during the tests.\n\n## Styling\n\nCheck formatting:\n\n```sh\nbun format\n```\n\nLint everything:\n\n```sh\nbun lint\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffirstbatchxyz%2Ffirstbatch-sdk-ts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffirstbatchxyz%2Ffirstbatch-sdk-ts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffirstbatchxyz%2Ffirstbatch-sdk-ts/lists"}