@iqai/adk 0.0.1

package/.changeset/README.md

@@ -0,0 +1,8 @@
+# Changesets
+
+Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works
+with multi-package repos, or single-package repos to help you version and publish your code. You can
+find the full documentation for it [in our repository](https://github.com/changesets/changesets)
+
+We have a quick list of common questions to get you started engaging with this project in
+[our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md)

package/.changeset/config.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@3.1.1/schema.json",
+  "changelog": "@changesets/cli/changelog",
+  "commit": false,
+  "fixed": [],
+  "linked": [],
+  "access": "restricted",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "ignore": []
+}

package/.cursor/rules/aim.mdc

@@ -0,0 +1,31 @@
+---
+description:
+globs:
+alwaysApply: true
+---
+# Project Aim
+
+## Python to TypeScript Port
+
+The aim of this project is to port the adk-python implementation to TypeScript (adk-ts). When porting code:
+
+- Refer to the original implementation of the Python files
+- Replicate their logic faithfully in TypeScript
+- Ensure the core functionality remains identical
+- Maintain the same logical structure and components
+
+## Requirements
+
+1. **Logic Preservation**: The TypeScript implementation MUST maintain the same logical flow and behavior as the Python version.
+
+2. **Component Naming**: Core components should maintain conceptual naming parity with the Python version.
+
+3. **Architecture**: Follow the same architectural patterns and separation of concerns as the Python implementation.
+
+4. **File Organization**: Mirror the Python project's organizational structure where appropriate, adapting to TypeScript conventions.
+
+## Implementation Notes
+
+- Use TypeScript's type system to enhance the original Python implementation
+- Apply language-specific best practices for TypeScript while preserving the original logic
+- Adapt Python-specific patterns to TypeScript equivalents where direct ports aren't possible

package/.cursor/rules/naming-conventions.mdc

@@ -0,0 +1,42 @@
+---
+description:
+globs:
+alwaysApply: true
+---
+# File Naming Conventions
+
+## Kebab Case for File Names
+
+All files in this project should use kebab-case for naming. This means:
+
+- All lowercase letters
+- Words separated by hyphens
+- No spaces or underscores
+- No PascalCase or camelCase
+
+### Examples:
+
+✅ Good:
+- `base-tool.ts`
+- `google-search-tool.ts`
+- `exit-loop-tool.ts`
+- `llm-agent.ts`
+- `memory-service.ts`
+
+❌ Bad:
+- `BaseTool.ts`
+- `GoogleSearchTool.ts`
+- `exit_loop_tool.ts`
+- `LlmAgent.ts`
+- `memoryService.ts`
+
+## Class and Interface Naming
+
+While files use kebab-case, TypeScript classes and interfaces should still follow standard conventions:
+
+- Classes and Interfaces: PascalCase (e.g., `class BaseTool`, `interface ToolConfig`)
+- Methods and Properties: camelCase (e.g., `runAsync()`, `getDeclaration()`)
+
+## Implementation Note
+
+This standardization helps maintain consistency across the codebase and aligns with common TypeScript ecosystem practices.

package/.cursor/rules/no-comments.mdc

@@ -0,0 +1,39 @@
+---
+description:
+globs:
+alwaysApply: true
+---
+# Code Documentation Guidelines
+
+## Commenting Philosophy
+
+This project follows a minimalist approach to code comments, focusing on clarity through well-structured, self-documenting code.
+
+## Comment Guidelines
+
+1. **Documentation Comments Only**: Add comments only when they provide documentation value. The code itself should be clear enough to understand without excessive comments.
+
+2. **No Line-by-Line Comments**: Avoid explaining each line of code with a comment. This creates maintenance overhead and often becomes outdated.
+
+3. **Method-Level Documentation**: Place concise documentation comments above methods/functions to explain:
+   - Purpose of the method
+   - Complex logic that may not be immediately obvious
+   - Any important side effects
+
+4. **Class-Level Documentation**: Document classes with a brief description of their purpose and responsibility.
+
+5. **Interface Documentation**: Document interfaces with clear descriptions of their intent and contract.
+
+## When to Use Comments
+
+✅ **Good Use of Comments**:
+- Explaining "why" something is done a certain way
+- Documenting complex algorithms
+- Flagging future enhancements (TODO comments)
+- Documenting API interfaces
+
+❌ **Avoid Comments For**:
+- Explaining obvious code
+- Duplicating what the code already clearly states
+- Commenting out unused code (delete it instead)
+- Line-by-line explanations

package/.cursor/rules/paths.mdc

@@ -0,0 +1,6 @@
+---
+description:
+globs:
+alwaysApply: true
+---
+You can find the path of the adk-python at the root : adk-python/

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Agent Development Kit (ADK) Contributors
+
+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, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE. 

package/README.md

@@ -0,0 +1,260 @@
+<div align="center">
+  <img src="adk-typescript.jpg" alt="ADK TypeScript Logo" width="100%"/>
+
+  <p align="center">
+    A robust framework for building AI agents with multi-provider LLM support
+  </p>
+
+  <p align="center">
+    <a href="https://www.npmjs.com/package/@iqai/adk">
+      <img src="https://img.shields.io/npm/v/@iqai/adk" alt="npm version" />
+    </a>
+    <a href="https://www.npmjs.com/package/@iqai/adk">
+      <img src="https://img.shields.io/npm/dm/@iqai/adk" alt="npm downloads" />
+    </a>
+    <a href="https://github.com/IQAIcom/adk-ts/blob/main/LICENSE">
+      <img src="https://img.shields.io/npm/l/@iqai/adk" alt="license" />
+    </a>
+    <a href="https://github.com/IQAIcom/adk-ts">
+      <img src="https://img.shields.io/github/stars/IQAIcom/adk-ts?style=social" alt="github stars" />
+    </a>
+  </p>
+  
+  <p align="center">
+    <a href="https://pontus-devoteam.github.io/adk-typescript/" target="_blank">
+      <img src="https://img.shields.io/badge/Docs-View_Documentation-blue?style=for-the-badge&logo=readthedocs" alt="View Documentation" />
+    </a>
+  </p>
+</div>
+
+## 🚀 Features
+
+- **🤖 Multi-provider Support**: Seamlessly switch between OpenAI, Anthropic, or Google LLMs
+- **🛠️ Tool System**: Create and use custom tools with declarative schemas
+- **🔄 Agent Loop**: Complete implementation of the agent reasoning loop with tool execution
+- **📡 Streaming Support**: Real-time streaming responses from LLMs
+- **🔒 Authentication**: Flexible auth system for secure API access
+- **💾 Memory Systems**: Persistent memory capabilities for stateful agents
+
+## 📚 Quick Start
+
+### 1. Installation
+
+```bash
+# Using npm
+npm install @iqai/adk
+
+# Using yarn
+yarn add @iqai/adk
+
+# Using pnpm
+pnpm add @iqai/adk
+```
+
+### 2. Configure Environment
+
+Create a `.env` file in your project root with your API keys:
+
+```env
+OPENAI_API_KEY=your_openai_api_key_here
+ANTHROPIC_API_KEY=your_anthropic_api_key_here
+GOOGLE_API_KEY=your_google_api_key_here
+```
+
+### 3. Create Your First Agent
+
+```typescript
+import { Agent } from '@iqai/adk';
+import dotenv from 'dotenv';
+
+// Load environment variables
+dotenv.config();
+
+// Create a basic agent
+const agent = new Agent({
+  name: "simple_assistant",
+  model: "gemini-2.5-flash-preview-05-20", // Or "gpt-4-turbo" or "claude-3-opus"
+  description: "A simple assistant",
+  instructions: "You are a helpful assistant. Answer questions concisely."
+});
+
+// Run the agent
+async function main() {
+  const response = await agent.run({
+    messages: [{ role: 'user', content: 'Hello, who are you?' }]
+  });
+
+  console.log(response.content);
+}
+
+main().catch(console.error);
+```
+
+## 📖 Documentation
+
+**[View Full Documentation](https://pontus-devoteam.github.io/adk-typescript/)**
+
+Our comprehensive documentation includes:
+
+- Complete API reference
+- Architecture overview
+- Integration guides
+- Advanced usage examples
+- Provider-specific configurations
+
+## 🏗️ Project Status
+
+⚠️ **Early Development Stage**
+
+This project is currently in early development and should be considered alpha software. While it's functional and can be used in projects, you may encounter:
+
+- Breaking changes between versions
+- APIs that may evolve based on user feedback
+- Features that are still being stabilized
+
+Current development status:
+
+- ✅ Core agent framework
+- ✅ Basic OpenAI implementation
+- ✅ Initial Anthropic integration
+- ✅ Initial Google/Gemini integration
+- ✅ Tool system foundation
+- ✅ Basic memory system
+- 🚧 Enhanced error handling
+- 🚧 Improved type safety
+- 🚧 Extended provider features
+- 🚧 Advanced memory capabilities
+- ⬜ Comprehensive testing suite
+- ⬜ Performance optimizations
+- ⬜ Advanced streaming features
+
+We welcome feedback, bug reports, and contributions! Please check the [issues page](https://github.com/IQAIcom/adk-ts/issues) for known issues or to report new ones.
+
+## 📚 Usage Examples
+
+### Agent with Tools
+
+```typescript
+import { Agent, BaseTool } from '@iqai/adk';
+
+// Create a custom calculator tool
+class CalculatorTool extends BaseTool {
+  constructor() {
+    super({
+      name: 'calculator',
+      description: 'Perform basic calculations'
+    });
+  }
+
+  getDeclaration() {
+    return {
+      name: this.name,
+      description: this.description,
+      parameters: {
+        type: 'object',
+        properties: {
+          operation: {
+            type: 'string',
+            enum: ['add', 'subtract', 'multiply', 'divide']
+          },
+          a: { type: 'number' },
+          b: { type: 'number' }
+        },
+        required: ['operation', 'a', 'b']
+      }
+    };
+  }
+
+  async runAsync(args) {
+    const { operation, a, b } = args;
+    
+    switch(operation) {
+      case 'add': return { result: a + b };
+      case 'subtract': return { result: a - b };
+      case 'multiply': return { result: a * b };
+      case 'divide': return { result: a / b };
+      default: throw new Error(`Unknown operation: ${operation}`);
+    }
+  }
+}
+
+// Create an agent with the tool
+const agent = new Agent({
+  name: "calculator_assistant",
+  model: "gpt-4-turbo",
+  instructions: "You can perform calculations. Use the calculator tool when asked about math.",
+  tools: [new CalculatorTool()]
+});
+
+// Run the agent
+const response = await agent.run({
+  messages: [{ role: 'user', content: 'What is 24 * 7?' }]
+});
+```
+
+### Agent with Memory
+
+```typescript
+import { Agent, PersistentMemoryService } from '@iqai/adk';
+import path from 'path';
+
+// Create a memory service
+const memoryService = new PersistentMemoryService({
+  storageDir: path.join(__dirname, '.memory'),
+  createDir: true
+});
+
+// Create an agent with memory
+const agent = new Agent({
+  name: "memory_assistant",
+  model: "gemini-2.5-flash-preview-05-20",
+  instructions: "You have persistent memory. Remember user preferences.",
+  memoryService,
+  userId: 'user-123'
+});
+
+// Run the agent with a session ID for persistence
+const response = await agent.run({
+  messages: [{ role: 'user', content: 'Remember that I like blue.' }],
+  sessionId: 'persistent-session-1'
+});
+```
+
+## 🧪 Example Projects
+
+The `examples/` directory contains several example implementations:
+
+```bash
+# Run simple agent example
+npm run example:simple
+
+# Run tool usage example
+npm run example:tool
+
+# Run memory usage example
+npm run example:memory
+
+# Run multi-provider example
+npm run example:multi
+
+# Run Anthropic tool example
+npm run example:anthropic
+```
+
+## 🤝 Contributing
+
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🌟 Show your support
+
+Give a ⭐️ if this project helped you!

package/biome.json

@@ -0,0 +1,47 @@
+{
+	"$schema": "https://biomejs.dev/schemas/1.9.4/schema.json",
+	"vcs": {
+		"enabled": false,
+		"clientKind": "git",
+		"useIgnoreFile": false
+	},
+	"files": {
+		"ignoreUnknown": false,
+		"ignore": [
+			"node_modules/**",
+			"coverage/**",
+			"dist/**",
+			"*.lock",
+			"*.log",
+			"docs/**"
+		]
+	},
+	"formatter": {
+		"enabled": true,
+		"indentStyle": "tab"
+	},
+	"organizeImports": {
+		"enabled": true
+	},
+	"linter": {
+		"enabled": true,
+		"rules": {
+			"recommended": true,
+			"suspicious": {
+				"noExplicitAny": "off"
+			},
+			"complexity": {
+				"noForEach": "off",
+				"noStaticOnlyClass": "off"
+			},
+			"style": {
+				"noNonNullAssertion": "off"
+			}
+		}
+	},
+	"javascript": {
+		"formatter": {
+			"quoteStyle": "double"
+		}
+	}
+}