npm-ai-hooks 1.0.0-beta.0

package/.env.example

@@ -0,0 +1,14 @@
+# OpenAI API key (for OpenRouter OpenAI models or standalone OpenAI)
+AI_HOOK_OPENAI_KEY=your_openai_api_key_here
+
+# OpenRouter API key
+AI_HOOK_OPENROUTER_KEY=your_openrouter_api_key_here
+
+# Groq API key
+AI_HOOK_GROQ_KEY=your_groq_api_key_here
+
+# Default provider (optional)
+# AI_HOOK_DEFAULT_PROVIDER=openrouter
+
+# Default model is handled by code, so no need to set it here
+# AI_HOOK_DEFAULT_MODEL=

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,35 @@
+
+---
+
+## 3. `CODE_OF_CONDUCT.md`
+
+```md
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and maintainers pledge to make participation in this project a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment include:
+
+- Using welcoming and inclusive language  
+- Being respectful of differing viewpoints and experiences  
+- Gracefully accepting constructive criticism  
+- Focusing on what is best for the community  
+- Showing empathy towards other community members
+
+Examples of unacceptable behavior include:
+
+- Harassment of public or private forms  
+- Trolling, insulting/derogatory comments  
+- Publishing others’ private information without permission  
+- Other conduct which could reasonably be considered inappropriate
+
+## Enforcement
+
+Instances of abusive behavior may be reported to the maintainers via [issues](https://github.com/RealTeebot/npm-ai-hooks/issues).  
+All complaints will be reviewed and addressed appropriately.
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/).

package/CONTRIBUTING.md

@@ -0,0 +1,88 @@
+# Contributing to npm-ai-hooks
+
+👋 Thanks for your interest in contributing to **npm-ai-hooks**!  
+This project is maintained by the [RealTeebot](https://github.com/RealTeebot) organization and welcomes community involvement at all levels — from bug fixes and documentation to major feature development.
+
+---
+
+## 🛠️ Development Setup
+
+1. **Fork** the repository and clone your fork:
+
+```bash
+git clone https://github.com/your-username/npm-ai-hooks.git
+cd npm-ai-hooks
+
+npm install
+
+npm run dev
+
+npm run test
+
+npm-ai-hooks/
+├─ src/
+│  ├─ index.ts          # Main entry
+│  ├─ wrap.ts           # Core hook wrapper logic
+│  ├─ cache.ts          # Caching engine
+│  ├─ cost.ts           # Cost estimation utilities
+│  ├─ errors.ts         # Unified error handling
+│  ├─ providers/        # Provider adapters
+│  │   ├─ openai.ts
+│  │   ├─ claude.ts
+│  │   └─ ...
+├─ examples/
+│  ├─ node-basic/
+│  └─ react-basic/
+├─ tests/
+└─ ...
+
+✨ Contributing Guidelines
+
+TypeScript Only: All code must be written in TypeScript with strict typing enabled.
+
+Linting: Run npm run lint before committing.
+
+Formatting: Code must pass Prettier formatting checks.
+
+Commit Style: Use Conventional Commits
+ (e.g., feat: add caching to DeepSeek provider).
+
+Tests: Add unit/integration tests for any new features or bug fixes.
+
+📦 Adding a New Provider
+
+Create a new file in src/providers/ (e.g., mistral.ts)
+
+Implement the required interface:
+
+export const mistralProvider: Provider = {
+  name: "mistral",
+  isAvailable: () => !!process.env.AI_HOOK_MISTRAL_KEY,
+  generate: async (prompt, options) => { /* API call logic */ },
+  models: ["mistral-medium", "mistral-large"]
+};
+
+
+Register the provider in providers/index.ts
+
+Add documentation and tests.
+
+🧪 Testing
+
+We use Jest for unit testing and Playwright for integration tests where relevant.
+
+npm run test
+npm run test:watch
+
+📣 Communication
+
+Issues: GitHub Issues
+
+Discussions: GitHub Discussions
+
+Pull Requests: Always create a PR to the main branch
+
+🙏 Credits
+
+Maintained with ❤️ by RealTeebot
+ and contributors.

package/EXAMPLES.md

@@ -0,0 +1,53 @@
+7. EXAMPLES.md
+# Usage Examples – npm-ai-hooks
+
+## 🧠 In a React Frontend
+
+Install:
+
+```bash
+npm install npm-ai-hooks
+
+
+Example:
+
+import { wrap } from "npm-ai-hooks";
+
+const summarize = wrap((text: string) => text, { task: "summarize" });
+
+export function App() {
+  const [result, setResult] = useState("");
+
+  const handleClick = async () => {
+    const res = await summarize("Explain server components in React.");
+    setResult(res.output);
+  };
+
+  return (
+    <div>
+      <button onClick={handleClick}>Summarize</button>
+      <p>{result}</p>
+    </div>
+  );
+}
+
+⚙️ In a Node.js Backend
+import { wrap } from "npm-ai-hooks";
+
+const explain = wrap((input: string) => input, { task: "explain" });
+
+app.post("/explain", async (req, res) => {
+  const result = await explain(req.body.text);
+  res.json(result);
+});
+
+
+This works with Express, NestJS, Fastify, Next.js API routes — anything Node-compatible.
+
+
+---
+
+
+---
+
+✅ **With these files in place**, your repository will be structured like a professional, enterprise-ready open-source project:

package/LICENSE

@@ -0,0 +1,15 @@
+MIT License
+
+Copyright (c) 2025 RealTeebot
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND...

package/ROADMAP.md

@@ -0,0 +1,22 @@
+# Roadmap – npm-ai-hooks
+
+✅ v0.1.0 (MVP)
+- [x] Basic `wrap()` functionality
+- [x] OpenAI + Claude support
+- [x] Error handling and cost estimation
+- [x] Caching layer
+
+🚀 v0.2.0
+- [ ] Provider auto-discovery CLI
+- [ ] More built-in tasks (e.g., classify, code explain)
+- [ ] React hook wrapper (`useAI`)
+
+💡 v0.3.0
+- [ ] Streaming support
+- [ ] Local model support (Ollama / Llama.cpp)
+- [ ] SDK for Python (bridge)
+
+🧠 Long-Term Vision
+- Unified dashboard for usage + cost
+- Plugin ecosystem (community providers, custom tasks)
+- Serverless deployment starter template

package/Readme.md

@@ -0,0 +1,268 @@
+# npm-ai-hooks 🧠
+
+**Universal AI Hook Layer for Node.js – one wrapper for all AI providers.**
+Inject LLM-like behavior into any JavaScript or TypeScript function with a single line, without writing prompts, handling SDKs, or locking into any provider.
+
+---
+
+## 🚀 Features
+
+* ✨ **Universal API:** Works with OpenAI, Claude, Gemini, DeepSeek, Groq, and more — out of the box.
+* 🔁 **Plug & Play:** Wrap any function and instantly give it AI-powered behavior.
+* 📦 **Zero Prompting:** Built-in task templates (summarize, explain, translate, sentiment, rewrite, code-review, etc.)
+* 🔄 **Auto Provider Selection:** Detects available providers automatically from environment variables.
+* ⚙️ **Configurable:** Choose provider, model, temperature, and more per call.
+* 🔒 **Error Safe:** Handles invalid keys, unauthorized models, rate limits, and more gracefully.
+* 💰 **Cost Awareness:** Estimate and log token usage and cost before and after calls.
+* 🧠 **Caching:** Prevents duplicate calls and charges by caching results intelligently.
+* 🔌 **Extensible:** Add your own providers and custom tasks easily.
+* 🛠️ **Debug Friendly:** Full debug logging with `AI_HOOK_DEBUG=true`.
+
+---
+
+## 📦 Installation
+
+```bash
+npm install npm-ai-hooks
+# or
+yarn add npm-ai-hooks
+```
+
+---
+
+## 🧪 Quick Start
+
+```js
+const ai = require("npm-ai-hooks");
+
+// Wrap any function
+const summarize = ai.wrap(text => text, { task: "summarize" });
+
+(async () => {
+  const result = await summarize("Node.js is a JavaScript runtime built on Chrome's V8...");
+  console.log(result.output); // "Node.js is a JS runtime for building server-side apps."
+})();
+```
+
+---
+
+## 🔑 Environment Setup
+
+Set one or more API keys in your `.env` file (or system environment):
+
+```
+AI_HOOK_OPENAI_KEY=sk-...
+AI_HOOK_CLAUDE_KEY=sk-...
+AI_HOOK_GEMINI_KEY=AIza...
+AI_HOOK_DEEPSEEK_KEY=ds-...
+AI_HOOK_GROQ_KEY=gr-...
+
+AI_HOOK_DEFAULT_PROVIDER=openai
+```
+
+If no provider is explicitly set, `npm-ai-hooks` will:
+
+1. Use `AI_HOOK_DEFAULT_PROVIDER` if defined.
+2. Auto-detect the first available provider.
+3. Throw an error if none are available.
+
+---
+
+## 📚 Usage Examples
+
+### 1. Basic Summarization
+
+```js
+const summarize = ai.wrap(text => text, { task: "summarize" });
+console.log(await summarize("Long article text..."));
+```
+
+---
+
+### 2. Custom Provider + Model
+
+```js
+const explain = ai.wrap(t => t, {
+  task: "explain",
+  provider: "claude",
+  model: "claude-3-opus"
+});
+
+console.log(await explain("Explain quantum computing like I'm 10."));
+```
+
+---
+
+### 3. AI Pipelines
+
+```js
+const summarize = ai.wrap(t => t, { task: "summarize" });
+const translate = ai.wrap(t => t, { task: "translate", lang: "fr" });
+
+const result = await translate(await summarize("Long technical article..."));
+console.log(result.output); // Résumé en français
+```
+
+---
+
+### 4. Built-in Tasks
+
+| Task         | Description                              |
+| ------------ | ---------------------------------------- |
+| `summarize`  | Summarize text into concise form         |
+| `translate`  | Translate text to a target language      |
+| `explain`    | Explain complex text simply              |
+| `rewrite`    | Rephrase text for tone/clarity           |
+| `sentiment`  | Analyze emotional tone of text           |
+| `codeReview` | Review code and provide feedback         |
+| `docstring`  | Generate function documentation comments |
+
+---
+
+## ⚙️ Advanced Configuration
+
+### Caching
+
+```js
+const summarize = ai.wrap(t => t, { task: "summarize", cache: true });
+```
+
+* Cache keys are based on task + input + model.
+* TTL defaults to 24h (configurable).
+* Clear manually with:
+
+  ```js
+  await ai.clearCache();
+  ```
+
+---
+
+### Cost Awareness
+
+Get detailed cost + token usage metadata:
+
+```js
+const summarize = ai.wrap(t => t, { task: "summarize" });
+const result = await summarize(longText);
+
+console.log(result.meta);
+/*
+{
+  provider: "openai",
+  model: "gpt-4o",
+  cached: false,
+  estimatedCostUSD: 0.0013,
+  totalCostUSD: 0.0012,
+  inputTokens: 326,
+  outputTokens: 127,
+  latencyMs: 812
+}
+*/
+```
+
+---
+
+### Error Handling
+
+All errors follow a unified structure:
+
+```js
+try {
+  await summarize("...");
+} catch (err) {
+  console.error(err);
+  /*
+  {
+    code: "MODEL_NOT_ALLOWED",
+    message: "Your API key does not have access to gpt-4o",
+    provider: "openai",
+    suggestion: "Upgrade your plan or choose another model."
+  }
+  */
+}
+```
+
+---
+
+### Debugging
+
+Enable verbose logs:
+
+```
+AI_HOOK_DEBUG=true
+```
+
+Output example:
+
+```
+[ai-hooks] Using provider: OpenAI (gpt-4o)
+[ai-hooks] Estimated cost: $0.0012
+[ai-hooks] Cache: MISS
+[ai-hooks] Response received in 812ms
+```
+
+---
+
+## 🧩 Extending with Custom Providers
+
+You can add support for any model/service:
+
+```js
+ai.registerProvider({
+  name: "my-llm",
+  isAvailable: () => !!process.env.MY_LLM_KEY,
+  generate: async (prompt, options) => {
+    const res = await fetch("https://my-llm.com/api", { ... });
+    return await res.text();
+  }
+});
+```
+
+---
+
+## 🧠 Roadmap
+
+* [ ] Streaming output support
+* [ ] Cost ceiling + auto-fallbacks
+* [ ] Rate limiter
+* [ ] Multi-turn conversation API
+* [ ] Local model support (llama.cpp, Ollama)
+* [ ] VSCode extension for code-gen
+
+---
+
+## 🛠️ Project Structure (Planned)
+
+```
+npm-ai-hooks/
+├─ src/
+│  ├─ index.js
+│  ├─ wrap.js
+│  ├─ cache.js
+│  ├─ cost.js
+│  ├─ errors.js
+│  ├─ providers/
+│  │   ├─ openai.js
+│  │   ├─ claude.js
+│  │   ├─ gemini.js
+│  │   ├─ deepseek.js
+│  │   ├─ groq.js
+│  │   └─ index.js
+├─ tests/
+├─ package.json
+├─ README.md
+└─ LICENSE
+```
+
+---
+
+## 🤝 Contributing
+
+Contributions, ideas, and feedback are welcome!
+Please open an issue or submit a pull request.
+
+---
+
+## 📜 License
+
+MIT © 2025 `npm-ai-hooks` Team

package/SECURITY.md

@@ -0,0 +1,30 @@
+# Security Policy
+
+## Supported Versions
+
+We actively support the latest major release and security patches for the previous one.
+
+| Version | Supported |
+|--------|-----------|
+| 1.x.x  | ✅        |
+| 0.x.x  | ❌        |
+
+---
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability, **DO NOT** open a public GitHub issue.
+
+Instead, please report it privately by emailing:  
+**security@realteebot.dev**
+
+We take all security issues seriously and will respond within 48 hours.
+
+---
+
+## Disclosure Process
+
+1. We confirm and investigate the vulnerability.
+2. We create a patch and test the fix.
+3. We coordinate a release and notify users.
+4. We credit the reporter (if they wish).

package/examples/basic/explain.ts

@@ -0,0 +1,18 @@
+import { wrap } from "../../src/wrap";
+
+const explain = wrap((text: string) => text, { task: "explain" });
+
+async function run() {
+  try {
+    const result = await explain("Quantum computing is complex.");
+    console.log(result.output);
+  } catch (err: any) {
+    if (err && typeof err.pretty === "function") {
+      err.pretty();
+    } else {
+      console.error(err.message || err);
+    }
+  }
+}
+
+run();

package/examples/basic/rewrite.ts

@@ -0,0 +1,10 @@
+import { wrap } from "../../src/wrap";
+
+const rewrite = wrap((text: string) => text, { task: "rewrite" });
+
+async function run() {
+  const result = await rewrite("AI code can sometimes be confusing.");
+  console.log(result.output);
+}
+
+run();

package/examples/basic/sentiment.ts

@@ -0,0 +1,10 @@
+import { wrap } from "../../src/wrap";
+
+const sentiment = wrap((text: string) => text, { task: "sentiment" });
+
+async function run() {
+  const result = await sentiment("I love using AI-Hooks for my projects!");
+  console.log(result.output);
+}
+
+run();

package/examples/basic/summarize.ts

@@ -0,0 +1,10 @@
+import { wrap } from "../../src/wrap";
+
+const summarize = wrap((text: string) => text, { task: "summarize" });
+
+async function run() {
+  const result = await summarize("OpenRouter is a powerful AI integration tool.");
+  console.log(result.output);
+}
+
+run();

package/examples/basic/translate.ts

@@ -0,0 +1,10 @@
+import { wrap } from "../../src/wrap";
+
+const translate = wrap((text: string) => text, { task: "translate", targetLanguage: "Urdu" });
+
+async function run() {
+  const result = await translate("Hello everyone! Welcome to AI demos.");
+  console.log(result.output);
+}
+
+run();

package/examples/demo.ts

@@ -0,0 +1,16 @@
+import { wrap } from "../src";
+
+const summarize = wrap((text: string) => text, { task: "summarize" });
+
+(async () => {
+  try {
+    const result = await summarize("OpenRouter is a great tool for AI integration...");
+    console.log(result.output);
+  } catch (err: any) {
+    if (err.pretty) {
+      err.pretty(); // prints nice error with suggestions
+    } else {
+      console.error(err);
+    }
+  }
+})();

package/examples/model-switch/groq-default.ts

@@ -0,0 +1,10 @@
+import { wrap } from "../../src/wrap";
+
+const explain = wrap((text: string) => text, { task: "explain", provider: "groq" });
+
+async function run() {
+  const result = await explain("Groq provides fast text AI models.");
+  console.log(result.output);
+}
+
+run();

package/examples/model-switch/groq-text2.ts

@@ -0,0 +1,10 @@
+import { wrap } from "../../src/wrap";
+
+const explain = wrap((text: string) => text, { task: "explain", provider: "groq", model: "allam-2-7b" });
+
+async function run() {
+  const result = await explain("Groq's text-2 model is versatile for many tasks.");
+  console.log(result.output);
+}
+
+run();

package/examples/model-switch/openrouter-default.ts

@@ -0,0 +1,10 @@
+import { wrap } from "../../src/wrap";
+
+const summarize = wrap((text: string) => text, { task: "summarize", provider: "openrouter" });
+
+async function run() {
+  const result = await summarize("OpenRouter makes AI integration seamless.");
+  console.log(result.output);
+}
+
+run();

package/examples/model-switch/openrouter-gpt5.ts

@@ -0,0 +1,10 @@
+import { wrap } from "../../src/wrap";
+
+const summarize = wrap((text: string) => text, { task: "summarize", provider: "openrouter", model: "openai/gpt-5-pro" });
+
+async function run() {
+  const result = await summarize("OpenRouter supports multiple models including GPT-5.");
+  console.log(result.output);
+}
+
+run();

package/examples/model-switch/wrong-models.ts

@@ -0,0 +1,21 @@
+import { wrap } from "../../src/wrap";
+
+async function run() {
+  // Wrong OpenRouter model
+  try {
+    const wrongOpenRouter = wrap((text: string) => text, { task: "summarize", provider: "openrouter", model: "invalid-model" as any });
+    await wrongOpenRouter("Test text");
+  } catch (err: unknown) {
+    console.error("❌ OpenRouter error:", err);
+  }
+
+  // Wrong Groq model
+  try {
+    const wrongGroq = wrap((text: string) => text, { task: "explain", provider: "groq", model: "invalid-groq-model" as any });
+    await wrongGroq("Test text");
+  } catch (err: unknown) {
+    console.error("❌ Groq error:", err);
+  }
+}
+
+run();