{"_id":"@blueprintlabio/time-ai","_rev":"3-403496e268766e4612f1589f3530c94b","name":"@blueprintlabio/time-ai","dist-tags":{"latest":"0.1.2"},"versions":{"0.1.0":{"name":"@blueprintlabio/time-ai","version":"0.1.0","keywords":["llm","ai","time","date","parsing","temporal","chrono","natural-language","prompt","context"],"author":{"name":"Blueprint Lab"},"license":"MIT","_id":"@blueprintlabio/time-ai@0.1.0","maintainers":[{"name":"yail259","email":"yaillives@gmail.com"}],"homepage":"https://github.com/BlueprintLabIO/time-ai#readme","bugs":{"url":"https://github.com/BlueprintLabIO/time-ai/issues"},"dist":{"shasum":"f022afbfec626c9d0d17aa1947b59f3caa6e7b78","tarball":"https://registry.npmjs.org/@blueprintlabio/time-ai/-/time-ai-0.1.0.tgz","fileCount":15,"integrity":"sha512-IQb8oo+endO6m1MDgpLTQ9J7egUsm563JgPjY7UTXHpm23heiK5ATbTN49D6io2cUanKnICusUX+Irzg2WK8fQ==","signatures":[{"sig":"MEUCID+7eyS68W1A8ypka2tQfgLnxMIPeGKjokfdOYwablFoAiEA1P1tbPB3iXft5juBieWFBjFXsD9LOa+MySonFg+ynTU=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":48599},"main":"dist/index.js","types":"dist/index.d.ts","gitHead":"cc684d3d12a99d72027a82f3727005306816d07e","scripts":{"dev":"tsc --watch","lint":"eslint src/**/*.ts","test":"jest","build":"tsc","format":"prettier --write src/**/*.ts","test:watch":"jest --watch","test:monitor":"node scripts/test-monitor.js once","test:coverage":"jest --coverage","test:monitor:continuous":"node scripts/test-monitor.js continuous"},"_npmUser":{"name":"yail259","email":"yaillives@gmail.com"},"repository":{"url":"git+https://github.com/BlueprintLabIO/time-ai.git","type":"git"},"_npmVersion":"10.9.0","description":"Time-aware utilities for LLM applications - parse dates, add temporal context, and optimize prompts","directories":{},"_nodeVersion":"22.12.0","dependencies":{"chrono-node":"^2.8.4"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^29.7.0","eslint":"^8.57.0","ts-jest":"^29.1.2","prettier":"^3.2.5","typescript":"^5.4.5","@types/jest":"^29.5.12","@types/node":"^20.12.7","@typescript-eslint/parser":"^7.7.0","@typescript-eslint/eslint-plugin":"^7.7.0"},"_npmOperationalInternal":{"tmp":"tmp/time-ai_0.1.0_1757939060579_0.6548600715206883","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@blueprintlabio/time-ai","version":"0.1.1","keywords":["llm","ai","time","date","parsing","temporal","chrono","natural-language","prompt","context"],"author":{"name":"Blueprint Lab"},"license":"MIT","_id":"@blueprintlabio/time-ai@0.1.1","maintainers":[{"name":"yail259","email":"yaillives@gmail.com"}],"homepage":"https://github.com/BlueprintLabIO/time-ai#readme","bugs":{"url":"https://github.com/BlueprintLabIO/time-ai/issues"},"dist":{"shasum":"a23f51ab29150e102df0ae8eeb0cf2609349bfec","tarball":"https://registry.npmjs.org/@blueprintlabio/time-ai/-/time-ai-0.1.1.tgz","fileCount":15,"integrity":"sha512-iqgpsBRIHlVa4PE5Mqxm8LHrmgya25N/+b8lIR97ib1l2Wn1N1BB9yLZGnsMb935eapO3DR/PClFrcxRNqzzHg==","signatures":[{"sig":"MEUCIQD+KTzASQdy2nikUQdP9IpqWDrsPU87jUelvCU4SYsM3AIgVBCAS4x8lFo86HqGAbDSoApEN8IsZVOAjWChJTXUA3g=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":57327},"main":"dist/index.js","types":"dist/index.d.ts","gitHead":"3d68c146efd71932875b39da7c91146d1640084d","scripts":{"dev":"tsc --watch","lint":"eslint src/**/*.ts","test":"jest","build":"tsc","format":"prettier --write src/**/*.ts","test:watch":"jest --watch","test:monitor":"node scripts/test-monitor.js once","publish:major":"npm version major && npm publish","publish:minor":"npm version minor && npm publish","publish:patch":"npm version patch && npm publish","test:coverage":"jest --coverage","prepublishOnly":"npm run build && npm test","coverage:update-readme":"node scripts/update-coverage-readme.js","test:monitor:continuous":"node scripts/test-monitor.js continuous"},"_npmUser":{"name":"yail259","email":"yaillives@gmail.com"},"repository":{"url":"git+https://github.com/BlueprintLabIO/time-ai.git","type":"git"},"_npmVersion":"10.9.0","description":"Time-aware utilities for LLM applications - parse dates, add temporal context, and optimize prompts","directories":{},"_nodeVersion":"22.12.0","dependencies":{"chrono-node":"^2.8.4"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^29.7.0","eslint":"^8.57.0","ts-jest":"^29.1.2","prettier":"^3.2.5","typescript":"^5.4.5","@types/jest":"^29.5.12","@types/node":"^20.12.7","@typescript-eslint/parser":"^7.7.0","@typescript-eslint/eslint-plugin":"^7.7.0"},"_npmOperationalInternal":{"tmp":"tmp/time-ai_0.1.1_1758020979995_0.47208962948658195","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@blueprintlabio/time-ai","version":"0.1.2","description":"Time-aware utilities for LLM applications - parse dates, add temporal context, and optimize prompts","main":"dist/index.js","types":"dist/index.d.ts","scripts":{"build":"tsc","dev":"tsc --watch","test":"jest","test:watch":"jest --watch","test:coverage":"jest --coverage","coverage:update-readme":"node scripts/update-coverage-readme.js","test:monitor":"node scripts/test-monitor.js once","test:monitor:continuous":"node scripts/test-monitor.js continuous","lint":"eslint src/**/*.ts","format":"prettier --write src/**/*.ts","prepublishOnly":"npm run build && npm test","publish:patch":"npm version patch && npm publish","publish:minor":"npm version minor && npm publish","publish:major":"npm version major && npm publish"},"keywords":["llm","ai","time","date","parsing","temporal","chrono","natural-language","prompt","context"],"author":{"name":"Blueprint Lab"},"license":"MIT","dependencies":{"chrono-node":"^2.8.4","dayjs":"^1.11.18"},"devDependencies":{"@types/jest":"^29.5.12","@types/node":"^20.12.7","@typescript-eslint/eslint-plugin":"^7.7.0","@typescript-eslint/parser":"^7.7.0","eslint":"^8.57.0","jest":"^29.7.0","prettier":"^3.2.5","ts-jest":"^29.1.2","typescript":"^5.4.5"},"repository":{"type":"git","url":"git+https://github.com/BlueprintLabIO/time-ai.git"},"bugs":{"url":"https://github.com/BlueprintLabIO/time-ai/issues"},"homepage":"https://github.com/BlueprintLabIO/time-ai#readme","publishConfig":{"access":"public"},"_id":"@blueprintlabio/time-ai@0.1.2","gitHead":"3d68c146efd71932875b39da7c91146d1640084d","_nodeVersion":"22.12.0","_npmVersion":"10.9.0","dist":{"integrity":"sha512-G9aPyo63LFSPM2nodaYxgjbEow/fmuLS/GCfn8aNUPCAqX69s1Gt16/Nd4IqVjvphQihQfsHHizmwb7yBFs3pg==","shasum":"fa6b3dba23abc5a45531d7fa8697ab1d9d2c37ab","tarball":"https://registry.npmjs.org/@blueprintlabio/time-ai/-/time-ai-0.1.2.tgz","fileCount":15,"unpackedSize":62478,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCICaf57OH9TnlJou4Ys0aRLVHR3LD4DnyeKY/8eoWdgGJAiAm2T1EwdHm4BKVcKY13hLgXUn+b4AfKoV21IdDo1gqIQ=="}]},"_npmUser":{"name":"yail259","email":"yaillives@gmail.com"},"directories":{},"maintainers":[{"name":"yail259","email":"yaillives@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/time-ai_0.1.2_1758026380222_0.7527362733770215"},"_hasShrinkwrap":false}},"time":{"created":"2025-09-15T12:24:20.496Z","modified":"2025-09-16T12:39:40.580Z","0.1.0":"2025-09-15T12:24:20.755Z","0.1.1":"2025-09-16T11:09:40.193Z","0.1.2":"2025-09-16T12:39:40.409Z"},"bugs":{"url":"https://github.com/BlueprintLabIO/time-ai/issues"},"author":{"name":"Blueprint Lab"},"license":"MIT","homepage":"https://github.com/BlueprintLabIO/time-ai#readme","keywords":["llm","ai","time","date","parsing","temporal","chrono","natural-language","prompt","context"],"repository":{"type":"git","url":"git+https://github.com/BlueprintLabIO/time-ai.git"},"description":"Time-aware utilities for LLM applications - parse dates, add temporal context, and optimize prompts","maintainers":[{"name":"yail259","email":"yaillives@gmail.com"}],"readme":"# time-ai\n\n> Time-aware utilities for LLM applications - parse dates, add temporal context, and optimize prompts\n\n[![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](http://www.typescriptlang.org/)\n![Coverage](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/BlueprintLabIO/time-ai/main/badges/coverage.json)\n\n## Links\n\n- Project site: https://time-ai.blueprintlab.io\n- NPM package: https://www.npmjs.com/package/@blueprintlabio/time-ai\n\n## Features\n\n- **Natural Language Date Parsing** - Parse dates from text like \"next Friday\", \"end of month\", \"tomorrow at 3pm\"\n- **LLM Context Enhancement** - Add temporal context to prompts for better AI understanding\n- **Multiple Formatting Strategies** - Preserve, normalize, or hybrid date formatting\n- **Timezone Aware** - Handle dates across different timezones\n- **Locale Support** - Format dates according to different locales\n- **TypeScript First** - Full type safety and IntelliSense support\n\n## Installation\n\n```bash\nnpm install @blueprintlabio/time-ai\n```\n\n## Quick Start\n\n```typescript\nimport { TimeAI } from '@blueprintlabio/time-ai';\n\nconst timeAI = new TimeAI({\n  timezone: 'America/New_York',\n  locale: 'en-US'\n});\n\n// Enhance prompts with temporal context\nconst result = timeAI.enhancePrompt(\"Schedule a meeting next Friday at 2pm\");\nconsole.log(result.enhancedText);\n// \"Schedule a meeting next Friday (2025-09-19) at 2pm\"\n\n// Add current date context to any prompt\nconst prompt = timeAI.addContext(\"What's the weather like?\");\nconsole.log(prompt);\n// Current date: 2025-09-15 (Sunday, 2025)\n// Timezone: America/New_York\n// \n// What's the weather like?\n\n// Parse dates from natural language\nconst date = timeAI.parseDate(\"tomorrow at 3pm\");\nconsole.log(date?.resolvedDate);\n// Date object for tomorrow at 3pm\n```\n\n## API Reference\n\n### TimeAI Class\n\n#### Constructor\n\n```typescript\nnew TimeAI(config?: TimeAIConfig)\n```\n\n**Config Options:**\n- `timezone?: string` - Target timezone (default: system timezone)\n- `locale?: string` - Locale for formatting (default: system locale)\n- `strategy?: 'preserve' | 'normalize' | 'hybrid'` - Date formatting strategy (default: 'hybrid')\n- `includeContext?: boolean` - Whether to include temporal context (default: true)\n\n#### Methods\n\n##### `enhancePrompt(text: string, options?: { strategy?: 'preserve' | 'normalize' | 'hybrid' }): EnhancedPrompt`\n\nEnhance text with temporal context and date disambiguation.\n\n```typescript\nconst result = timeAI.enhancePrompt(\"Meet next Friday\", { strategy: 'hybrid' });\n// Returns: {\n//   originalText: \"Meet next Friday\",\n//   enhancedText: \"Meet next Friday (2025-09-19)\", \n//   context: \"Current date: 2025-09-15...\",\n//   extractions: [...],\n//   tokensAdded: 12\n// }\n```\n\n**Strategies:**\n- `preserve` - Keep original date text unchanged\n- `normalize` - Replace with absolute dates (YYYY-MM-DD)\n- `hybrid` - Combine relative and absolute: \"next Friday (2025-09-19)\"\n\n##### `parseDate(text: string): DateExtraction | null`\n\nParse the first date found in text.\n\n```typescript\nconst extraction = timeAI.parseDate(\"tomorrow at 3pm\");\n// Returns: {\n//   originalText: \"tomorrow at 3pm\",\n//   resolvedDate: Date,\n//   confidence: 0.95,\n//   type: 'relative',\n//   start: 0,\n//   end: 16,\n//   grain: 'hour'\n// }\n```\n\n##### `parseDates(text: string): DateExtraction[]`\n\nParse all dates found in text.\n\n##### `formatDate(date: Date, style: FormatStyle): string`\n\nFormat dates for different use cases.\n\n**Format Styles:**\n- `context` - \"Today is Monday, September 15, 2025\"\n- `hybrid` - \"next Friday (Sep 19)\"\n- `compact` - \"2025-09-15\"\n- `human` - \"Monday, September 15, 2025\"\n- `iso` - \"2025-09-15T00:00:00.000Z\"\n- `relative` - \"in 3 days\"\n\n##### `addContext(prompt: string): string`\n\nAdd temporal context to any prompt.\n\n```typescript\ntimeAI.addContext(\"What should I do today?\");\n// \"Current date: 2025-09-15 (Sunday, 2025)\\nTimezone: America/New_York\\n\\nWhat should I do today?\"\n```\n\n### Convenience Functions\n\n```typescript\nimport { enhancePrompt, parseDate, addContext } from '@blueprintlabio/time-ai';\n\n// Use default instance\nconst result = enhancePrompt(\"Meet tomorrow\");\nconst date = parseDate(\"next week\");\nconst prompt = addContext(\"Hello world\");\n\n// Or with custom config\nconst result = enhancePrompt(\"Meet tomorrow\", { timezone: 'UTC' });\n```\n\n### Legacy Compatibility\n\nFor easy migration from existing time utilities:\n\n```typescript\nimport { getCurrentTimeContext, formatDateForOpenAI, addDateContextToPrompt } from '@blueprintlabio/time-ai';\n\n// Drop-in replacements for your existing functions\nconst context = getCurrentTimeContext();\nconst formatted = formatDateForOpenAI(new Date());\nconst enhanced = addDateContextToPrompt(\"Your prompt here\");\n```\n\n## Use Cases\n\n### LLM Prompt Enhancement\n\n```typescript\nconst timeAI = new TimeAI({ strategy: 'hybrid' });\n\n// Before\nconst prompt = \"Schedule a demo call next Tuesday and send reminder tomorrow\";\n\n// After\nconst enhanced = timeAI.enhancePrompt(prompt);\nconsole.log(enhanced.enhancedText);\n// \"Schedule a demo call next Tuesday (2025-09-23) and send reminder tomorrow (2025-09-16)\"\n```\n\n### Task Scheduling\n\n```typescript\nconst timeAI = new TimeAI({ strategy: 'normalize' });\n\nconst userInput = \"Remind me to call client next Friday\";\nconst result = timeAI.enhancePrompt(userInput);\n\n// Extract absolute date for scheduling\nconst dateExtraction = result.extractions[0];\nconst scheduleDate = dateExtraction.resolvedDate; // Exact Date object\n```\n\n### Multi-timezone Applications\n\n```typescript\n// User in New York\nconst nyTimeAI = new TimeAI({ timezone: 'America/New_York' });\n\n// User in London  \nconst londonTimeAI = new TimeAI({ timezone: 'Europe/London' });\n\n// Same relative date, different absolute times\nconst prompt = \"Meet tomorrow at 9am\";\nconst nyResult = nyTimeAI.enhancePrompt(prompt);\nconst londonResult = londonTimeAI.enhancePrompt(prompt);\n```\n\n### Chatbot Context\n\n```typescript\nconst timeAI = new TimeAI();\n\nfunction processMessage(userMessage: string) {\n  // Add temporal awareness to every conversation\n  const enhanced = timeAI.addContext(userMessage);\n  \n  // Send to LLM with temporal context\n  return callLLM(enhanced);\n}\n```\n\n## Advanced Usage\n\n### Custom Date Patterns\n\nThe library uses [chrono-node](https://github.com/wanasit/chrono) internally and includes custom parsers for business contexts:\n\n- \"next business day\" \n- \"end of this week\" (Friday)\n- \"end of quarter\"\n- \"next workday\"\n\n### Timezone Handling\n\n```typescript\nconst timeAI = new TimeAI({ timezone: 'UTC' });\n\n// Change timezone dynamically\ntimeAI.setTimezone('Asia/Tokyo');\ntimeAI.setLocale('ja-JP');\n\n// Check timezone-aware comparisons\nconst isTodayInTokyo = timeAI.isToday(someDate);\n```\n\n### Performance Considerations\n\nThe library provides token count estimation for LLM optimization:\n\n```typescript\nconst result = timeAI.enhancePrompt(\"Long prompt with many dates...\");\nconsole.log(`Added ${result.tokensAdded} tokens`);\n\n// Use compact context for token-sensitive applications\nconst timeAI = new TimeAI({ includeContext: false });\n```\n\n## Test Coverage\n\n<!-- COVERAGE-START -->\nCoverage from latest test run:\n\n- Statements: 92.45%\n- Branches: 85.26%\n- Functions: 88.88%\n- Lines: 93.18%\n<!-- COVERAGE-END -->\n\n## Contributing\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add some amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## License\n\nMIT © [Blueprint Lab](https://github.com/BlueprintLabIO)\n\n## Related Projects\n\n- [chrono-node](https://github.com/wanasit/chrono) - Natural language date parser\n- [date-fns](https://date-fns.org/) - Modern JavaScript date utility library\n- [dayjs](https://day.js.org/) - Lightweight date library\n","readmeFilename":"README.md"}