{"_id":"@aman5062/easy-ai","name":"@aman5062/easy-ai","dist-tags":{"alpha":"0.1.0-alpha.0","latest":"0.1.0-alpha.0"},"versions":{"0.1.0-alpha.0":{"name":"@aman5062/easy-ai","version":"0.1.0-alpha.0","description":"Express.js for AI: a TypeScript framework for structured outputs, traces, RAG, and cost-aware AI features","main":"./dist/index.js","module":"./dist/index.mjs","types":"./dist/index.d.ts","bin":{"easy-ai":"dist/cli.js"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"}},"scripts":{"build":"tsup src/index.ts src/cli.ts --format cjs,esm --dts --clean","dev":"tsup src/index.ts src/cli.ts --format cjs,esm --dts --watch","test":"tsx tests/release-smoke.test.ts","start":"node dist/cli.js","link:local":"npm link","prepublishOnly":"npm run build"},"keywords":["ai","llm","rag","openai","structured-outputs","traces","developer-tools","prompt-engineering","anthropic","easy","framework","chatgpt","gpt","machine-learning","natural-language-processing","nlp","embeddings","vector-search","semantic-search","document-processing","pdf","typescript"],"sideEffects":false,"author":"","license":"MIT","publishConfig":{"access":"public","tag":"alpha"},"repository":{"type":"git","url":"git+https://github.com/yourusername/easy-ai.git"},"bugs":{"url":"https://github.com/yourusername/easy-ai/issues"},"homepage":"https://github.com/yourusername/easy-ai#readme","devDependencies":{"@types/node":"^20.11.0","tsup":"^8.0.1","tsx":"^4.7.0","typescript":"^5.3.3"},"dependencies":{"openai":"^4.28.0"},"engines":{"node":">=18.0.0"},"_id":"@aman5062/easy-ai@0.1.0-alpha.0","gitHead":"c4bc2a7f587d9f5615175af1c602cf84c911beac","_nodeVersion":"20.20.2","_npmVersion":"10.8.2","dist":{"integrity":"sha512-lvVWcrtqTpDV0AjZK0lx7oOv0ebTXD4B0POIl85eu7JXXU6zlrCaij3RWy3Hcum4yA/HpR2I+UYYGsx2VIwjWg==","shasum":"e36a7c22ccc3a4e1030032348fa4f4567c310677","tarball":"https://registry.npmjs.org/@aman5062/easy-ai/-/easy-ai-0.1.0-alpha.0.tgz","fileCount":12,"unpackedSize":118547,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIEguh4xb/slIxjdqY67j/t88vFMYQxF8N+creJf+8zHdAiEAtcLcwraL0Wfk0kAM9jVnG+HAcziCmMW7OBsA+LeSDgQ="}]},"_npmUser":{"name":"aman5062","email":"amank232004@gmail.com"},"directories":{},"maintainers":[{"name":"aman5062","email":"amank232004@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/easy-ai_0.1.0-alpha.0_1777542075261_0.6393420127531029"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-30T09:41:15.159Z","0.1.0-alpha.0":"2026-04-30T09:41:15.404Z","modified":"2026-04-30T09:41:15.603Z"},"maintainers":[{"name":"aman5062","email":"amank232004@gmail.com"}],"description":"Express.js for AI: a TypeScript framework for structured outputs, traces, RAG, and cost-aware AI features","homepage":"https://github.com/yourusername/easy-ai#readme","keywords":["ai","llm","rag","openai","structured-outputs","traces","developer-tools","prompt-engineering","anthropic","easy","framework","chatgpt","gpt","machine-learning","natural-language-processing","nlp","embeddings","vector-search","semantic-search","document-processing","pdf","typescript"],"repository":{"type":"git","url":"git+https://github.com/yourusername/easy-ai.git"},"bugs":{"url":"https://github.com/yourusername/easy-ai/issues"},"license":"MIT","readme":"# easy-ai\n\n`easy-ai` is a TypeScript AI helper for simple chat, structured output, and plugin-based orchestration.\n\n## Install\n\n```bash\nnpm install easy-ai\n```\n\n## Configure\n\nSet your API key before running the CLI or your app:\n\n```bash\nexport OPENAI_API_KEY=\"your-api-key\"\n```\n\n## Use in code\n\n```typescript\nimport { createAI } from 'easy-ai';\n\nconst ai = createAI({ auto: true });\nconst answer = await ai.ask('What is artificial intelligence?');\nconsole.log(answer);\n```\n\n## Use the CLI\n\n```bash\nnpx easy-ai ask \"What is AI?\"\n```\n\n## Structured output\n\n```typescript\nconst profile = await ai.askStructured('Extract a short profile', {\n  outputSchema: {\n    description: 'Profile object',\n    schema: {\n      name: 'string',\n      role: 'string'\n    }\n  }\n});\n```\n\n## Notes\n\n- Node.js 18+ is required.\n- `QA_MOCK=true` can be used in local testing to avoid real API calls.\n- Build output is written to `dist/`.\n# 🧠 easy-ai\n\n[![NPM Version](https://img.shields.io/npm/v/easy-ai.svg)](https://www.npmjs.com/package/easy-ai)\n[![License](https://img.shields.io/npm/l/easy-ai.svg)](https://github.com/yourusername/easy-ai/blob/main/LICENSE)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue.svg)](https://www.typescriptlang.org/)\n[![Node](https://img.shields.io/badge/Node-%3E%3D18.0.0-green.svg)](https://nodejs.org/)\n\n**The magical AI backend framework that just works.**\n\nBuild AI features in seconds, not hours. No configs. No complexity. Just pure magic.\n\n```typescript\nimport { createAI } from \"easy-ai\";\n\nconst ai = createAI({ auto: true });\nconst answer = await ai.ask(\"Explain quantum computing\");\nconsole.log(answer);\n```\n\nThat's it. You're done. ✨\n\n---\n\n## 🚀 Quick Start (30 seconds)\n\n### Install\n\n```bash\nnpm install easy-ai\n```\n\nOr use the setup script:\n\n```bash\ngit clone https://github.com/yourusername/easy-ai.git\ncd easy-ai\n./setup.sh\n```\n\n### Set API Key\n\n```bash\nexport OPENAI_API_KEY=\"your-key-here\"\n```\n\n### Use\n\n```typescript\nimport { createAI } from \"easy-ai\";\n\nconst ai = createAI({ auto: true });\nconst res = await ai.ask(\"What is AI?\");\nconsole.log(res);\n```\n\n---\n\n## 🌟 Why easy-ai?\n\n| Other Libraries | easy-ai |\n|----------------|---------|\n| 200 lines of config | 3 lines of code |\n| Choose models manually | Auto-selects best model |\n| Build RAG from scratch | Built-in, auto-detected |\n| Manage costs yourself | Cost-optimized by default |\n| Debug with console.log | `.debug()` shows everything |\n\n---\n\n## ✨ Auto Mode (The Magic)\n\nAuto mode is the heart of easy-ai. It automatically:\n\n- ✅ Detects if you need RAG\n- ✅ Processes documents intelligently\n- ✅ Chooses the right model (cheap vs powerful)\n- ✅ Optimizes for cost and speed\n- ✅ Caches responses semantically\n- ✅ Makes everything just work\n\n```typescript\nconst ai = createAI({ auto: true });\n\n// Simple query → uses gpt-3.5-turbo (cheap & fast)\nawait ai.ask(\"What's 2+2?\");\n\n// Complex query → uses gpt-4o-mini (powerful)\nawait ai.ask(\"Explain the philosophical implications of consciousness\");\n\n// With document → automatically uses RAG\nawait ai.ask(\"Summarize this PDF\", { \n  documents: [\"content here\"] \n});\n```\n\n**Zero configuration. Maximum intelligence.**\n\n---\n\n## 🔥 Real-World Examples\n\n### 1. Simple Q&A\n\n```typescript\nconst ai = createAI({ auto: true });\nconst answer = await ai.ask(\"What is TypeScript?\");\n```\n\n### 2. Document Analysis (Auto RAG)\n\n```typescript\nimport { createAI, useRAG } from \"easy-ai\";\n\nconst ai = createAI({ auto: true })\n  .use(useRAG({ file: \"./docs.pdf\" }));\n\nconst summary = await ai.ask(\"What are the key points?\");\n```\n\n### 3. Cost-Optimized Pipeline\n\n```typescript\nconst ai = createAI({ auto: true })\n  .use(useCache({ ttl: 3600 }))\n  .use(useRouter({ simple: \"gpt-3.5-turbo\", complex: \"gpt-4o-mini\" }));\n\nawait ai.ask(\"Hello\"); // Cached & cheap model\nconsole.log(ai.getUsage()); // { totalCost: 0.0001, cacheHits: 1 }\n```\n\n### 4. Debug Mode (Developer Love)\n\n```typescript\nconst ai = createAI({ auto: true }).debug();\n\nconst res = await ai.ask(\"Explain AI\");\n// 🔍 [DEBUG] Query: Explain AI\n// 🤖 [DEBUG] Model: gpt-3.5-turbo\n// 🎫 [DEBUG] Tokens: 150\n// 💰 [DEBUG] Cost: $0.000300\n```\n\n### 5. Production-Ready with Guards\n\n```typescript\nimport { createAI, useGuard, useCache } from \"easy-ai\";\n\nconst ai = createAI({ auto: true })\n  .use(useCache())\n  .use(useGuard({ \n    minLength: 20,\n    validate: (res) => !res.includes(\"error\")\n  }));\n\nconst answer = await ai.ask(\"Explain machine learning\");\n```\n\n---\n\n## 🧩 Plugin System\n\nExtend easy-ai with composable plugins:\n\n```typescript\nconst ai = createAI()\n  .use(useRAG({ file: \"docs.pdf\" }))      // Document processing\n  .use(useCache({ ttl: 3600 }))           // Semantic caching\n  .use(useRouter())                        // Smart model selection\n  .use(useGuard({ minLength: 10 }))       // Output validation\n  .use(useDebug());                        // Development insights\n```\n\n### Available Plugins\n\n| Plugin | Purpose | Example |\n|--------|---------|---------|\n| `useRAG()` | Document processing & retrieval | `useRAG({ file: \"doc.pdf\" })` |\n| `useCache()` | Semantic response caching | `useCache({ ttl: 3600 })` |\n| `useRouter()` | Auto model selection | `useRouter({ simple: \"gpt-3.5-turbo\" })` |\n| `useGuard()` | Output validation & retry | `useGuard({ minLength: 20 })` |\n| `useDebug()` | Development insights | `useDebug()` |\n\n---\n\n## 📊 Usage Tracking\n\n```typescript\nconst ai = createAI({ auto: true });\n\nawait ai.ask(\"Question 1\");\nawait ai.ask(\"Question 2\");\n\nconst stats = ai.getUsage();\nconsole.log(stats);\n// {\n//   totalTokens: 500,\n//   totalCost: 0.001,\n//   requestCount: 2,\n//   cacheHits: 0\n// }\n```\n\n## 🧾 Structured Outputs\n\n**How do you get JSON from easy-ai?** Use `askStructured()` when you need a parsed object instead of plain text.\n\n```typescript\nimport { createAI } from \"easy-ai\";\n\nconst ai = createAI({ auto: true });\n\nconst profile = await ai.askStructured<{ name: string; role: string }>(\n  \"Extract a developer profile from: Sam is a TypeScript engineer who builds AI tools.\",\n  {\n    outputSchema: {\n      description: \"Developer profile object\",\n      schema: {\n        name: \"string\",\n        role: \"string\"\n      }\n    }\n  }\n);\n\nconsole.log(profile.name);\n```\n\n## 🧭 Trace and Debug\n\n**How do you inspect what happened during a request?** Call `getTrace()` to see the execution timeline, then use `.debug()` for the full response object.\n\n```typescript\nconst ai = createAI({ auto: true });\nawait ai.ask(\"Explain AI routing\");\n\nconsole.log(ai.getTrace());\n```\n\n### Can I use an OpenAI-compatible provider?\n\nYes. Pass `baseURL` in the config to point at an OpenAI-compatible endpoint, or provide `fallbackModels` to keep the app resilient when the primary model is unavailable.\n\n```typescript\nconst ai = createAI({\n  auto: true,\n  apiKey: process.env.OPENAI_API_KEY,\n  baseURL: \"https://your-compatible-provider.example/v1\",\n  fallbackModels: [\"gpt-4o-mini\", \"gpt-3.5-turbo\"]\n});\n```\n\n---\n\n## 🎯 Design Philosophy\n\n1. **Simplicity > Flexibility** – Defaults should work for 90% of use cases\n2. **Speed > Abstraction** – Minimal overhead, maximum performance\n3. **DX First** – Developer experience is the top priority\n4. **Cost-Aware** – Optimize for cost without sacrificing quality\n5. **Just Works™** – No configs, no setup, no confusion\n\n---\n\n## ❓ Frequently Asked Questions\n\n### What is easy-ai?\n\neasy-ai is a TypeScript AI backend framework that helps developers build AI features with zero-config defaults, auto routing, RAG, caching, tracing, and structured outputs.\n\n### Why is easy-ai SEO and AEO friendly?\n\nThe documentation uses question-based headings, direct answers, concrete code examples, and predictable terminology so search engines and answer engines can extract useful snippets quickly.\n\n### How do I get a JSON response?\n\nUse `askStructured()` and provide an `outputSchema`. The framework asks the model for JSON-only output and parses the result for you.\n\n### How do I see the execution path?\n\nCall `getTrace()` after a request. It returns the ordered pipeline timeline with durations and skip reasons.\n\n### Is easy-ai only for OpenAI?\n\nThe current implementation uses OpenAI by default, but you can already point the SDK at OpenAI-compatible endpoints with `baseURL`. The provider layer also supports fallback models so apps can degrade more gracefully.\n\n---\n\n## 🏗️ How It Works\n\n```\n┌─────────────────────────────────────────────────┐\n│  Your Code: ai.ask(\"Explain this PDF\")         │\n└─────────────────┬───────────────────────────────┘\n                  │\n                  ▼\n┌─────────────────────────────────────────────────┐\n│  Auto Mode (Intelligence Layer)                 │\n│  • Detects RAG need                            │\n│  • Selects model (cheap vs powerful)           │\n│  • Optimizes cost & speed                      │\n└─────────────────┬───────────────────────────────┘\n                  │\n                  ▼\n┌─────────────────────────────────────────────────┐\n│  Plugin Pipeline                                │\n│  Cache → RAG → Router → Guard → Debug          │\n└─────────────────┬───────────────────────────────┘\n                  │\n                  ▼\n┌─────────────────────────────────────────────────┐\n│  LLM Provider (OpenAI)                          │\n└─────────────────┬───────────────────────────────┘\n                  │\n                  ▼\n┌─────────────────────────────────────────────────┐\n│  Response + Usage Stats                         │\n└─────────────────────────────────────────────────┘\n```\n\n---\n\n## 🏗️ Architecture\n\n```\neasy-ai/\n├── core/          # Engine & orchestration\n├── auto/          # Auto-mode intelligence\n├── llm/           # LLM provider abstraction\n├── plugins/       # Composable plugins\n│   ├── rag.ts\n│   ├── cache.ts\n│   ├── router.ts\n│   ├── guard.ts\n│   └── debug.ts\n└── types.ts       # TypeScript definitions\n```\n\n---\n\n## 🔧 Advanced Configuration\n\nWhile auto mode works out of the box, you can customize:\n\n```typescript\nconst ai = createAI({\n  auto: true,\n  apiKey: \"your-key\",\n  model: \"gpt-4\",\n  debug: false\n});\n```\n\n---\n\n## 🚦 API Reference\n\n### `createAI(config?)`\n\nCreates an AI instance.\n\n```typescript\nconst ai = createAI({ auto: true });\n```\n\n### `ai.ask(query, options?)`\n\nAsk a question.\n\n```typescript\nconst answer = await ai.ask(\"What is AI?\");\n```\n\n### `ai.use(plugin)`\n\nAdd a plugin.\n\n```typescript\nai.use(useCache());\n```\n\n### `ai.debug()`\n\nEnable debug mode.\n\n```typescript\nai.debug();\n```\n\n### `ai.getUsage()`\n\nGet usage statistics.\n\n```typescript\nconst stats = ai.getUsage();\n```\n\n---\n\n## 💡 Tips & Best Practices\n\n1. **Always use auto mode** – It's optimized for cost and performance\n2. **Enable caching** – Saves money on repeated queries\n3. **Use debug mode in dev** – Understand what's happening\n4. **Track usage** – Monitor costs in production\n5. **Validate outputs** – Use guards for critical applications\n\n---\n\n## 🖥️ CLI Tool\n\nUse easy-ai from the command line:\n\n```bash\n# Install globally\nnpm install -g easy-ai\n\n# Ask questions instantly\neasy-ai ask \"What is machine learning?\"\n\n# Debug mode\neasy-ai ask \"Explain AI\" --debug\n\n# Specify model\neasy-ai ask \"Write a poem\" --model gpt-4\n```\n\nPerfect for quick queries and testing!\n\n---\n\n## 🤝 Contributing\n\nWe'd love your help making easy-ai even better!\n\n---\n\n## 📄 License\n\nMIT\n\n---\n\n## 🎉 Why This Exists\n\nBecause building AI features shouldn't require a PhD. It should feel like using Express.js or React – simple, intuitive, and delightful.\n\n**Install it. Use it. Love it.** ❤️\n\n```bash\nnpm install easy-ai\n```\n","readmeFilename":"README.md","_rev":"1-937c15186ebf1e5c1733a25d3d206443"}