{"id":27689982,"url":"https://github.com/obaydmerz/agentic","last_synced_at":"2025-06-14T15:03:34.794Z","repository":{"id":288393176,"uuid":"964821390","full_name":"obaydmerz/agentic","owner":"obaydmerz","description":"A powerful agent framework for LLMs.","archived":false,"fork":false,"pushed_at":"2025-04-11T21:03:03.000Z","size":44,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-26T10:26:16.746Z","etag":null,"topics":["function-calling","llm"],"latest_commit_sha":null,"homepage":"https://agentic.gitbook.io/agentic","language":"JavaScript","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/obaydmerz.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}},"created_at":"2025-04-11T21:02:33.000Z","updated_at":"2025-04-11T21:16:12.000Z","dependencies_parsed_at":"2025-04-25T10:54:38.093Z","dependency_job_id":null,"html_url":"https://github.com/obaydmerz/agentic","commit_stats":null,"previous_names":["obaydmerz/agentic"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/obaydmerz/agentic","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/obaydmerz%2Fagentic","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/obaydmerz%2Fagentic/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/obaydmerz%2Fagentic/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/obaydmerz%2Fagentic/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/obaydmerz","download_url":"https://codeload.github.com/obaydmerz/agentic/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/obaydmerz%2Fagentic/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259835354,"owners_count":22918973,"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","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":["function-calling","llm"],"created_at":"2025-04-25T10:54:33.701Z","updated_at":"2025-06-14T15:03:34.782Z","avatar_url":"https://github.com/obaydmerz.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @obayd/agentic\n\n[![npm version](https://badge.fury.io/js/%40obayd%2Fagentic.svg)](https://badge.fury.io/js/%40obayd%2Fagentic)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nAgentic (**@obayd/agentic**) is a powerful, lightweight framework for building LLM agents in Node.js. It simplifies managing conversations, defining tools (function calling), handling streaming responses, and integrating with various Large Language Models.\n\n**[Full Documentation (GitBook)](https://agentic.gitbook.io/agentic)**\n\n## Key Features\n\n- **Fluent Tool Definition:** Easily define tools (functions) the LLM can call using a clean, chainable API (`Tool.make()...`).\n- **Toolpacks:** Group related tools and manage their availability.\n- **Streaming First:** Built with streaming in mind. Process LLM responses and tool events chunk by chunk using async generators.\n- **Flexible LLM Integration:** Works with any LLM API that provides streaming responses via a simple async generator function. Includes a helper `fetchResponseToStream` for common SSE formats.\n- **Conversation Management:** Automatically handles message history, system prompts, and the flow between user messages, assistant responses, and tool calls/results.\n- **Dynamic System Prompts:** Define system prompt content using strings, tools, toolpacks, or even functions for dynamic generation.\n- **Type-Safe:** Includes TypeScript declaration files (`.d.ts`) for excellent autocompletion and type safety, even when used in JavaScript projects.\n- **Zero-Dependency:** No external dependencies, making it easy to integrate with your existing project.\n\n## Installation\n\n```bash\nnpm install @obayd/agentic\n# or\nnpm install obaydmerz/agentic # Will install directly from github ( Not recommended )\n```\n\n## Quick Start\n\n```javascript\nimport { Conversation, Tool, fetchResponseToStream } from \"@obayd/agentic\";\n\n// 1. Define your LLM callback (Example using fetch and a helper)\n//    Replace with your actual LLM API call logic\nasync function* llmCallback(messages, options) {\n  // You can use OpenRouter or OpenAI here\n  const response = await fetch(\"YOUR_LLM_API_ENDPOINT\", {\n    method: \"POST\",\n    headers: {\n      \"Content-Type\": \"application/json\",\n      Authorization: `Bearer YOUR_API_KEY`,\n    },\n    body: JSON.stringify({\n      model: \"YOUR_MODEL_NAME\",\n      messages: messages, // Pass the formatted messages without modification\n      stream: true, // Ensure streaming is enabled\n\n      // Add any other required parameters for your API\n    }),\n  });\n\n  // Use the provided helper to process Server-Sent Events (SSE)\n  yield* fetchResponseToStream(response);\n}\n\n// 2. Define Tools\nconst getCurrentWeather = Tool.make(\"get_current_weather\")\n  .description(\"Gets the current weather for a specified location.\")\n  .param(\"location\", \"The city and state, e.g., San Francisco, CA\", {\n    required: true,\n    type: \"string\",\n  })\n  .param(\"unit\", \"Temperature unit\", {\n    enum: [\"celsius\", \"fahrenheit\"],\n    required: false,\n    type: \"string\",\n  })\n  .action(async (params) =\u003e {\n    // Simulate API call\n    await new Promise((resolve) =\u003e setTimeout(resolve, 50)); // Simulate delay\n    const location = params.location.toLowerCase();\n    const unit = params.unit || \"celsius\";\n    let temperature;\n\n    if (location.includes(\"tokyo\")) temperature = 15;\n    else if (location.includes(\"san francisco\")) temperature = 12;\n    else temperature = 20; // Default\n\n    if (unit === \"fahrenheit\") {\n      temperature = (temperature * 9) / 5 + 32;\n    }\n\n    return JSON.stringify({\n      // Return data for the LLM\n      temperature: temperature,\n      unit: unit,\n      condition: \"Sunny\", // Keep it simple for the example\n      location: params.location,\n    });\n  });\n\n// 3. Create a Conversation instance\nconst conversation = new Conversation(llmCallback);\n\n// 4. Define conversation content (system prompt, tools)\nconversation.content([\n  \"You are a helpful assistant.\",\n  getCurrentWeather, // Add the tool\n]);\n\n// 5. Send a message and process the response stream\nasync function runConversation() {\n  const userInput = \"What's the weather like in Tokyo?\";\n  console.log(`\\nUSER: ${userInput}`);\n  console.log(\"\\nASSISTANT:\");\n\n  let fullAssistantResponse = \"\";\n\n  try {\n    const stream = conversation.send(userInput);\n\n    for await (const event of stream) {\n      switch (event.type) {\n        case \"assistant\":\n          process.stdout.write(event.content); // Stream text to console\n          fullAssistantResponse += event.content;\n          break;\n        case \"tool.generating\":\n          // Optionally show that the LLM is generating raw tool input\n          // console.log(`\\n[Tool Generating Raw Chunk (${event.name})]: ${event.rawChunk}`);\n          break;\n        case \"tool.calling\":\n          process.stdout.write(\n            `\\n[Calling Tool: ${event.name} with params: ${JSON.stringify(\n              event.params\n            )}]`\n          );\n          if (event.raw) {\n            process.stdout.write(` [Raw: ${event.raw}]`);\n          }\n          process.stdout.write(\"\\n\");\n          break;\n        case \"tool\": // Tool result is back\n          console.log(`\\n[Tool Result (${event.name})]:`);\n          console.log(event.result); // Log the raw result object\n          // The conversation loop automatically sends this result back to the LLM\n          console.log(\"\\nASSISTANT (after tool):\"); // Indicate LLM will respond next\n          break;\n        case \"error\":\n          console.error(`\\n[Conversation Error]: ${event.content}`);\n          break;\n      }\n    }\n    console.log(\"\\n\\n--- Conversation End ---\");\n    // console.log(\"Full Assistant Response:\", fullAssistantResponse);\n    // console.log(\"Final Message History:\", conversation.messages);\n  } catch (error) {\n    console.error(\"\\n[Error Running Conversation]:\", error);\n  }\n}\n\nrunConversation();\n```\n\n## Documentation\n\nFor detailed usage, guides, and API reference, please visit the Full Documentation [GitBook](https://agentic.gitbook.io/agentic).\n\n## Contributing\n\nContributions are welcome! Please feel free to open an issue or submit a pull request.\n\n- Fork the repository.\n- Create your feature branch (git checkout -b feature/AmazingFeature).\n- Commit your changes (git commit -m 'Add some AmazingFeature').\n- Push to the branch (git push origin feature/AmazingFeature).\n- Open a Pull Request.\n\n## License\n\nDistributed under the MIT License. See LICENSE file for more information.\nAuthor\nAbderrahmene Merzoug (obaydmerz@gmail.com)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fobaydmerz%2Fagentic","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fobaydmerz%2Fagentic","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fobaydmerz%2Fagentic/lists"}