{"id":49328656,"url":"https://github.com/assim98/typesense-langgraph-checkpointer","last_synced_at":"2026-05-03T03:01:33.077Z","repository":{"id":354026834,"uuid":"1221841209","full_name":"assim98/typesense-langgraph-checkpointer","owner":"assim98","description":"LangGraph checkpoint saver backed by Typesense. Drop-in BaseCheckpointSaver implementation for Python and TypeScript — blazingly fast, in-memory checkpoint retrieval with automatic schema setup.","archived":false,"fork":false,"pushed_at":"2026-04-30T09:33:50.000Z","size":98,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-01T01:00:35.826Z","etag":null,"topics":["checkpoint","langchain","langgraph","typesense"],"latest_commit_sha":null,"homepage":"","language":"Python","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/assim98.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-26T18:46:05.000Z","updated_at":"2026-04-30T09:32:45.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/assim98/typesense-langgraph-checkpointer","commit_stats":null,"previous_names":["assim98/typesense-langgraph-checkpointer"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/assim98/typesense-langgraph-checkpointer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/assim98%2Ftypesense-langgraph-checkpointer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/assim98%2Ftypesense-langgraph-checkpointer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/assim98%2Ftypesense-langgraph-checkpointer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/assim98%2Ftypesense-langgraph-checkpointer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/assim98","download_url":"https://codeload.github.com/assim98/typesense-langgraph-checkpointer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/assim98%2Ftypesense-langgraph-checkpointer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32481556,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-30T13:12:12.517Z","status":"ssl_error","status_checked_at":"2026-04-30T13:12:06.837Z","response_time":57,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["checkpoint","langchain","langgraph","typesense"],"created_at":"2026-04-26T21:03:44.911Z","updated_at":"2026-05-02T02:01:02.603Z","avatar_url":"https://github.com/assim98.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# 🔍 typesense-langgraph-checkpointer\n\n**LangGraph checkpoint saver backed by [Typesense](https://typesense.org/) — for Python and JavaScript/TypeScript.**\n\n[![JS CI](https://github.com/assim98/typesense-langgraph-checkpointer/actions/workflows/js.yml/badge.svg)](https://github.com/assim98/typesense-langgraph-checkpointer/actions/workflows/js.yml)\n[![Python CI](https://github.com/assim98/typesense-langgraph-checkpointer/actions/workflows/python.yml/badge.svg)](https://github.com/assim98/typesense-langgraph-checkpointer/actions/workflows/python.yml)\n[![PyPI version](https://img.shields.io/pypi/v/typesense-langgraph-checkpointer?logo=python\u0026logoColor=white)](https://pypi.org/project/typesense-langgraph-checkpointer/)\n[![npm version](https://img.shields.io/npm/v/@assim98/typesense-langgraph-checkpointer?logo=npm)](https://www.npmjs.com/package/@assim98/typesense-langgraph-checkpointer)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n\n[Features](#-features) · [Installation](#-installation) · [Quick Start](#-quick-start) · [API Reference](#-api-reference) · [Development](#-development) · [Contributing](#-contributing)\n\n\u003c/div\u003e\n\n---\n\n## ✨ Features\n\n- **Drop-in LangGraph saver** — implements the full `BaseCheckpointSaver` interface\n- **Dual-language** — first-class Python **and** TypeScript packages from the same repo\n- **Blazingly fast search** — leverages Typesense's in-memory engine for sub-millisecond checkpoint retrieval\n- **Thread management** — full CRUD for threads, checkpoints, and pending writes\n- **Automatic schema setup** — call `setup()` once and collections are created for you\n- **Zero-config local dev** — Docker Compose included for instant Typesense instance\n\n---\n\n## 📦 Installation\n\n### Python\n\n```bash\npip install langgraph-checkpoint-typesense\n```\n\n### JavaScript / TypeScript\n\n```bash\nnpm install @typesense-langgraph/checkpoint\n```\n\n---\n\n## 🚀 Quick Start\n\n### Python\n\n```python\nimport typesense\nfrom langgraph_checkpoint_typesense import AsyncTypesenseSaver\n\n# 1. Create the saver\nsaver = AsyncTypesenseSaver.from_config(\n    host=\"localhost\",\n    port=8108,\n    api_key=\"your-api-key\",\n    protocol=\"http\",\n)\n\n# 2. Initialize collections (run once)\nawait saver.setup()\n\n# 3. Use with any LangGraph graph\nfrom langgraph.graph import StateGraph\n\ngraph = StateGraph(...)\n# ... define your nodes \u0026 edges ...\napp = graph.compile(checkpointer=saver)\n\n# 4. Invoke with a thread\nconfig = {\"configurable\": {\"thread_id\": \"my-thread\"}}\nresult = await app.ainvoke({\"input\": \"hello\"}, config)\n```\n\n### JavaScript / TypeScript\n\n```typescript\nimport { TypesenseSaver } from \"@typesense-langgraph/checkpoint\";\n\n// 1. Create the saver\nconst saver = TypesenseSaver.fromConfig({\n  host: \"localhost\",\n  port: 8108,\n  apiKey: \"your-api-key\",\n  protocol: \"http\",\n});\n\n// 2. Initialize collections (run once)\nawait saver.setup();\n\n// 3. Use with any LangGraph graph\nimport { StateGraph } from \"@langchain/langgraph\";\n\nconst graph = new StateGraph(...)\n  // ... define your nodes \u0026 edges ...\n  .compile({ checkpointer: saver });\n\n// 4. Invoke with a thread\nconst config = { configurable: { thread_id: \"my-thread\" } };\nconst result = await graph.invoke({ input: \"hello\" }, config);\n```\n\n---\n\n## ⚙️ Configuration\n\n| Parameter | Python | JS/TS | Default | Description |\n| --- | --- | --- | --- | --- |\n| Host | `host` | `host` | `localhost` | Typesense server hostname |\n| Port | `port` | `port` | `8108` | Typesense API port |\n| API Key | `api_key` | `apiKey` | — | Typesense API key |\n| Protocol | `protocol` | `protocol` | `http` | `http` or `https` |\n| Timeout | `connection_timeout_seconds` | `connectionTimeoutSeconds` | `5` | Connection timeout in seconds |\n\nYou can also pass a pre-configured Typesense `Client` directly to the constructor.\n\n---\n\n## 📖 API Reference\n\n### Python — `AsyncTypesenseSaver`\n\n| Method | Description |\n| --- | --- |\n| `from_config(cls, **kwargs)` | Create a saver from connection parameters |\n| `setup()` | Create Typesense collections if they don't exist |\n| `aget_tuple(config)` | Retrieve a checkpoint tuple |\n| `aput(config, checkpoint, metadata, new_versions)` | Store a checkpoint |\n| `aput_writes(config, writes, task_id)` | Store pending writes |\n| `alist(config, *, filter, before, limit)` | List checkpoint tuples |\n| `adelete_thread(thread_id)` | Delete all data for a thread |\n\n### JavaScript / TypeScript — `TypesenseSaver`\n\n| Method | Description |\n| --- | --- |\n| `fromConfig(config)` | Create a saver from connection parameters |\n| `setup()` | Create Typesense collections if they don't exist |\n| `getTuple(config)` | Retrieve a checkpoint tuple |\n| `put(config, checkpoint, metadata, newVersions)` | Store a checkpoint |\n| `putWrites(config, writes, taskId)` | Store pending writes |\n| `list(config, options?)` | Async-generator of checkpoint tuples |\n| `deleteThread(threadId)` | Delete all data for a thread |\n\n---\n\n## 🏗️ Architecture\n\n```mermaid\ngraph LR\n    A[\"LangGraph Runtime\"] --\u003e|checkpoint \u0026 writes| B[\"TypesenseSaver\"]\n    B --\u003e|upsert / search| C[\"Typesense\"]\n    C --\u003e D[(\"checkpoints collection\")]\n    C --\u003e E[(\"writes collection\")]\n    B --\u003e|getTuple / list| A\n```\n\nThe saver manages two Typesense collections:\n\n- **`langgraph_checkpoints`** — stores serialized checkpoint state, metadata, and channel versions\n- **`langgraph_writes`** — stores pending writes keyed by `(thread_id, checkpoint_id, task_id, idx)`\n\nBoth collections are created automatically by `setup()` with optimized schemas and sorting fields.\n\n---\n\n## 🛠️ Development\n\n### Prerequisites\n\n- [Docker](https://docs.docker.com/get-docker/)\n- Python ≥ 3.9\n- Node.js ≥ 22\n\n### Start Typesense\n\n```bash\ndocker compose up -d\n```\n\nDefault API key: `test-api-key` (override with `TYPESENSE_API_KEY` env var).\n\n### Python\n\n```bash\ncd python\npython -m venv .venv \u0026\u0026 source .venv/bin/activate\npip install -e \".[dev]\"\npytest tests/ -v\n```\n\n### JavaScript / TypeScript\n\n```bash\ncd js\nnpm ci\nnpm run build\nnpm test\n```\n\n---\n\n## 🤝 Contributing\n\nContributions are welcome! Please read the [Contributing Guide](CONTRIBUTING.md) and the [Code of Conduct](CODE_OF_CONDUCT.md) before opening a PR.\n\n---\n\n## 📄 License\n\nThis project is licensed under the [MIT License](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fassim98%2Ftypesense-langgraph-checkpointer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fassim98%2Ftypesense-langgraph-checkpointer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fassim98%2Ftypesense-langgraph-checkpointer/lists"}