{"id":28948860,"url":"https://github.com/programming-sai/ctxiq","last_synced_at":"2025-10-07T08:28:23.771Z","repository":{"id":300019398,"uuid":"1004879400","full_name":"Programming-Sai/CtxIQ","owner":"Programming-Sai","description":"Context and memory orchestration toolkit for building smarter AI assistants with TypeScript.","archived":false,"fork":false,"pushed_at":"2025-09-18T14:47:49.000Z","size":1783,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-18T17:23:53.932Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/Programming-Sai.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,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-06-19T10:16:47.000Z","updated_at":"2025-09-18T14:47:53.000Z","dependencies_parsed_at":"2025-07-10T08:28:51.118Z","dependency_job_id":"7d9425f0-95e7-460f-b386-7ffb7f249e3d","html_url":"https://github.com/Programming-Sai/CtxIQ","commit_stats":null,"previous_names":["programming-sai/ctxiq"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Programming-Sai/CtxIQ","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Programming-Sai%2FCtxIQ","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Programming-Sai%2FCtxIQ/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Programming-Sai%2FCtxIQ/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Programming-Sai%2FCtxIQ/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Programming-Sai","download_url":"https://codeload.github.com/Programming-Sai/CtxIQ/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Programming-Sai%2FCtxIQ/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278742642,"owners_count":26037864,"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","status":"online","status_checked_at":"2025-10-07T02:00:06.786Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":[],"created_at":"2025-06-23T11:06:07.884Z","updated_at":"2025-10-07T08:28:23.766Z","avatar_url":"https://github.com/Programming-Sai.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CtxIQ\n\n[![CI](https://github.com/Programming-Sai/CtxIQ/actions/workflows/ci.yml/badge.svg)](https://github.com/Programming-Sai/CtxIQ/actions/workflows/ci.yml)\n[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)\n[![npm version](https://img.shields.io/npm/v/ctxiq.svg)](https://www.npmjs.com/package/ctxiq)\n[![Status](https://img.shields.io/badge/development-active-brightgreen.svg)](#)\n[![Status](https://img.shields.io/badge/status-WIP-orange.svg)](#)\n\nContext and memory orchestration toolkit for building smarter AI assistants in TypeScript.\n\n---\n\n\u003e [!WARNING]  \n\u003e This project is under active development.\n\u003e Expect frequent updates and breaking changes until the first stable release.  \n\u003e Follow for progress or contribute!\n\n## ![CtxIQ Flow](./CtxIQ.png)\n\n## 🧠 Overview / Motivation\n\nBuilding AI assistants isn’t just about calling a model—it’s about **managing context**.  \nEvery real-world assistant must juggle ongoing conversations, control token budgets, and decide when to summarize or trim history.  \nWithout a structured toolkit, developers often reinvent fragile, one-off solutions for memory, persistence, and prompt construction.\n\n**CtxIQ** solves this by providing a **lightweight, TypeScript-first toolkit** for context and memory orchestration.  \nIt gives you composable building blocks—session management, token counting, pluggable persistence, and an abstract LLM caller—so you can focus on _what_ your assistant does instead of _how_ it keeps track of the past.\n\nDesigned to be **framework-agnostic** and **fully typed**, CtxIQ works in Node.js, the browser, or serverless environments, making it a reliable foundation for chatbots, copilots, and any multi-turn AI experience.\n\n---\n\n## ✨ Features\n\n- **Conversation Management** – Create, load, and persist multiple conversation sessions with a single manager.\n- **Token Budgeting** – Estimate prompt tokens, reserve space for summaries, and prevent model overflow with pluggable counters.\n- **Prompt Building** – Assemble clean, model-ready prompt messages with optional automatic summarization.\n- **Extensible LLM Caller** – Swap in your own LLM provider (OpenAI, Groq, etc.) or use the included mock caller for testing.\n- **Pluggable Persistence** – Save and restore sessions using adapters (e.g. browser `LocalStorage`) or roll your own.\n- **React Hooks** – `useConversation` and `useSession` provide easy integration in React apps.\n- **TypeScript First** – Fully typed API with clear interfaces and autocomplete support for a smooth developer experience.\n- **Framework Agnostic** – Works in Node.js, browsers, and serverless runtimes without extra dependencies.\n\n---\n\n## ⚡ Quick Start\n\nInstall from npm:\n\n```bash\nnpm install ctxiq\n# or\nyarn add ctxiq\n```\n\nCreate a simple conversation session:\n\n```typescript\nimport { ConversationManager } from \"ctxiq\";\n\n// 1️⃣ Initialize a manager (optionally pass configs like token budgets)\nconst manager = new ConversationManager();\n\n// 2️⃣ Create a session\nconst session = manager.createSession(\"demo-session\");\n\n// 3️⃣ Add a user message (ConversationSession will assign an id if you omit it)\nsession.addMessage({\n  role: \"user\",\n  content: \"Hello, CtxIQ!\",\n  // tokens optional, the session will compute if missing\n});\n\n// 4️⃣ Build a prompt for your LLM (buildPrompt is async if you provide an async summarizer)\nconst promptMessages = await session.buildPrompt();\n\n// 5️⃣ Optionally format for your provider (if you provided an llmFormatter, use getLLMMessages)\nconst providerInput = await session.getLLMMessages(); // returns provider-shaped array or default {role, content}[]\n\n// 6️⃣ Send to your LLM of choice (pseudo-code)\nconst reply = await myLLM.call(providerInput); // your adapter handles provider specifics\n\n// 7️⃣ Store the assistant’s reply back into the session\nsession.addMessage({\n  role: \"assistant\",\n  content: typeof reply === \"string\" ? reply : JSON.stringify(reply), // adapt as needed\n});\n\nconsole.log(session.toJSON());\n```\n\n---\n\n## 🧩 Core Concepts\n\nCtxIQ is built from small, composable pieces that work together:\n\n- **ConversationManager** – The top-level orchestrator.  \n  Creates, loads, lists, and deletes sessions. Handles global configuration like token budgets and storage adapters.\n\n- **ConversationSession** – Represents a single ongoing conversation.  \n  Stores messages, builds prompts, and triggers optional summarization.\n\n- **TokenManager** – Estimates and tracks token usage.  \n  Supports pluggable counters (approximation or tiktoken) to prevent overflow and reserve space for summaries.\n\n- **LLMCaller** – Abstract interface for sending prompts to an LLM.  \n  Includes a `MockLLMCaller` for tests and demos; real adapters (OpenAI, Groq, etc.) can be added as needed.\n\n- **Persistence Adapters** – Optional storage layer (e.g. `LocalStorageAdapter`) for saving and restoring sessions across page loads or server restarts.\n\n- **Prompt Builder** – Generates the final model-ready message array, automatically including summaries or trimming history based on token limits.\n\nThese components are **decoupled**: you can use only what you need, swap implementations, or extend with your own logic.\n\n---\n\n## 🔌 Adapters \u0026 Extensibility\n\nCtxIQ is designed to be **flexible and extensible**, allowing you to swap or extend functionality without changing core logic:\n\n- **Storage Adapters** – Persist session data anywhere:\n\n  - `LocalStorageAdapter` (browser-ready)\n  - IndexedDBAdaptor (planned)\n  - Custom adapters (implement the `StorageAdaptor` interface)\n\n- **LLM Adapters** – Connect to any LLM provider:\n\n  - `MockLLMCaller` (built-in for testing)\n  - OpenAI, Groq, or your custom provider\n  - Supports streaming responses and generic input/output types\n\n- **Token Managers** – Plug in different token counting strategies:\n\n  - `ApproxTokenCounter` (fast, heuristic-based)\n  - Optional `tiktoken` integration for exact counting\n\n- **Formatter Functions** – Each LLM adapter can export helper formatters to convert `Message[]` into provider-specific input.\n\nWith this design, you can **mix and match adapters, token managers, and LLMs** to suit your application needs.\n\n---\n\n## 📚 Examples / Recipes\n\nHere are some common patterns you can implement with CtxIQ:\n\n### 1️⃣ Basic conversation flow\n\n```ts\nconst manager = new ConversationManager();\nconst session = manager.createSession(\"example\");\n\n// add a user message\nsession.addMessage({ role: \"user\", content: \"Hello!\" });\n\n// build prompt (async if summariser is async)\nconst prompt = await session.buildPrompt();\n\n// format for provider or get default LLM messages\nconst llmInput = await session.getLLMMessages();\n\n// send to a provider (adapter-specific)\nconst providerResp = await mockLLM.call(llmInput);\n\n// store assistant reply\nsession.addMessage({\n  role: \"assistant\",\n  content:\n    typeof providerResp === \"string\"\n      ? providerResp\n      : JSON.stringify(providerResp),\n});\n```\n\n### 2️⃣ Persisting sessions in the browser\n\n```ts\nimport { LocalStorageAdapter, attachStorageAdaptor } from \"ctxiq\";\n\nconst manager = new ConversationManager();\nconst storage = new LocalStorageAdapter();\nattachStorageAdaptor(manager, storage);\n\nconst session = manager.createSession(\"persisted-demo\");\n```\n\n### 3️⃣ Using a custom LLM adapter\n\n- Implement the BaseLLMCaller interface (call\u003cTIn,TOut\u003e and optional stream)\n\n- Export a formatter function to convert Message[] into provider input\n\n- Inject your adapter into useSession or ConversationSession directly\n\n---\n\n## 📄 License\n\nThis project is licensed under the [MIT License](./LICENSE).\n\n---\n\nThank you for checking out **CtxIQ**!  \nContributions, feedback, and suggestions are welcome — feel free to open issues or pull requests.  \nStay tuned for updates as we continue building features and improving the library.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprogramming-sai%2Fctxiq","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprogramming-sai%2Fctxiq","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprogramming-sai%2Fctxiq/lists"}