{"_id":"@billaearnkit/sdk-alpha","_rev":"2-a3167932f10a702e53c2afa94897550b","name":"@billaearnkit/sdk-alpha","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.0":{"name":"@billaearnkit/sdk-alpha","version":"1.0.0","keywords":["ai","agent","tools","anthropic","gemini"],"author":{"name":"Your Name"},"license":"ISC","_id":"@billaearnkit/sdk-alpha@1.0.0","maintainers":[{"name":"snehendu098","email":"roysnehendupersonal@gmail.com"},{"name":"billalabs","email":"billalabsai@gmail.com"}],"homepage":"https://earnkit.com","bugs":{"url":"https://github.com/billa-labs/earnkit-sdk/issues"},"dist":{"shasum":"45f1e994d0611ddd78a20544474ee723fbd9a69a","tarball":"https://registry.npmjs.org/@billaearnkit/sdk-alpha/-/sdk-alpha-1.0.0.tgz","fileCount":22,"integrity":"sha512-UpfuwxJfCifSOUW4G3LvipXdD42iQiJsgPk0Y0dWGa0CY8mIrAh6J1pF/LwN62s1TmYCSFvQOCIaD5GvrCIIlw==","signatures":[{"sig":"MEUCIQD9orv7/aLaNlRvroiSA6Fmr5P5OKcaWGwDHKYNWXgGJAIgJ4t4V+QVT2qu1L3mtwagI2ait8GBHsmMEXqdFGE0E3M=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":31122},"main":"dist/index.js","types":"dist/index.d.ts","gitHead":"311261794184966a97b63d6620f75a3055df8ccc","scripts":{"dev":"tsx tests/index.ts","lint":"eslint src --ext .ts","test":"echo \"Error: no test specified\" && exit 1","build":"tsc","prepublishOnly":"npm run build"},"_npmUser":{"name":"snehendu098","email":"roysnehendupersonal@gmail.com"},"repository":{"url":"git+https://github.com/billa-labs/earnkit-sdk.git","type":"git"},"_npmVersion":"10.9.0","description":"SDK for creating and managing AI agents with tools","directories":{},"_nodeVersion":"22.11.0","dependencies":{"zod":"^3.24.2","chalk":"4.1.2","dotenv":"^16.4.7","@billaearnkit/alpha-core":"^0.0.1"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.3","ts-node":"^10.9.2","typescript":"^5.8.2","@types/chalk":"^2.2.4"},"peerDependencies":{"mongodb":"^5.0.0 || ^6.0.0"},"_npmOperationalInternal":{"tmp":"tmp/sdk-alpha_1.0.0_1743761526021_0.7700797477280812","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@billaearnkit/sdk-alpha","version":"1.0.1","description":"SDK for creating and managing AI agents with tools","main":"dist/index.js","types":"dist/index.d.ts","scripts":{"build":"tsc","prepublishOnly":"npm run build","lint":"eslint src --ext .ts","test":"echo \"Error: no test specified\" && exit 1","dev":"tsx tests/index.ts"},"keywords":["ai","agent","tools","anthropic","gemini"],"author":{"name":"Billa labs"},"license":"ISC","repository":{"type":"git","url":"git+https://github.com/billa-labs/earnkit-sdk.git"},"homepage":"https://earnkit.com","dependencies":{"@billaearnkit/alpha-core":"^0.0.1","chalk":"4.1.2","dotenv":"^16.4.7","zod":"^3.24.2"},"devDependencies":{"@types/chalk":"^2.2.4","typescript":"^5.8.2","ts-node":"^10.9.2","tsx":"^4.19.3"},"peerDependencies":{"mongodb":"^5.0.0 || ^6.0.0"},"_id":"@billaearnkit/sdk-alpha@1.0.1","gitHead":"a22825728e1431db0c0260aa703217332e02dd7a","bugs":{"url":"https://github.com/billa-labs/earnkit-sdk/issues"},"_nodeVersion":"22.11.0","_npmVersion":"10.9.0","dist":{"integrity":"sha512-GX2aPiBqzQDaW72/UsT5/q8XP/jSG/leB7RCJE/5GoWvDv4B8CFbyYmvYlmPTnZvyQCti4Hjcw2oRp8KEpD3ew==","shasum":"043a655bc338162e9ac6088f10ca7c3c94a9c4ba","tarball":"https://registry.npmjs.org/@billaearnkit/sdk-alpha/-/sdk-alpha-1.0.1.tgz","fileCount":22,"unpackedSize":44006,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDcg4BN3n7R5xE8tinRUwsb4Dea0gsG9oFk5MXvfovvaAIgOCXczPPu+WGriKK/ZG2JpLLTEtO4Cg0Qk17RBxvpAZ4="}]},"_npmUser":{"name":"snehendu098","email":"roysnehendupersonal@gmail.com"},"directories":{},"maintainers":[{"name":"snehendu098","email":"roysnehendupersonal@gmail.com"},{"name":"billalabs","email":"billalabsai@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sdk-alpha_1.0.1_1743781640519_0.8939507021467705"},"_hasShrinkwrap":false}},"time":{"created":"2025-04-04T10:12:05.921Z","modified":"2025-04-04T15:47:20.888Z","1.0.0":"2025-04-04T10:12:06.243Z","1.0.1":"2025-04-04T15:47:20.700Z"},"bugs":{"url":"https://github.com/billa-labs/earnkit-sdk/issues"},"author":{"name":"Billa labs"},"license":"ISC","homepage":"https://earnkit.com","keywords":["ai","agent","tools","anthropic","gemini"],"repository":{"type":"git","url":"git+https://github.com/billa-labs/earnkit-sdk.git"},"description":"SDK for creating and managing AI agents with tools","maintainers":[{"name":"snehendu098","email":"roysnehendupersonal@gmail.com"},{"name":"billalabs","email":"billalabsai@gmail.com"}],"readme":"# @billaearnkit/sdk-alpha\n\nA powerful TypeScript SDK for building AI agents with customizable tools and integrations, optimized for blockchain operations.\n\n## Overview\n\n`@billaearnkit/sdk-alpha` provides a framework for creating AI agents that can use various tools and integrations. The SDK is designed with flexibility in mind, allowing developers to build agents with domain-specific capabilities through a modular tool architecture.\n\n> **Important Note**: This SDK depends on `@billaearnkit/alpha-core` which is currently under heavy testing and development. Breaking changes may occur in future updates.\n\n## Table of Contents\n\n- [Installation](#installation)\n- [Core Concepts](#core-concepts)\n- [Getting Started](#getting-started)\n- [Project Structure](#project-structure)\n- [Creating Tools](#creating-tools)\n- [Creating Clients](#creating-clients)\n- [Agent State Management](#agent-state-management)\n- [Tool Orchestration](#tool-orchestration)\n- [Environment Variables](#environment-variables)\n- [Examples](#examples)\n- [Troubleshooting](#troubleshooting)\n- [Dependencies](#dependencies)\n\n## Installation\n\n```bash\nnpm install @billaearnkit/sdk-alpha\n# or\nyarn add @billaearnkit/sdk-alpha\n# or\nbun add @billaearnkit/sdk-alpha\n```\n\n## Core Concepts\n\n### Agent\n\nThe `Agent` class is the main entry point of the SDK. It handles:\n\n- Tool registration and management\n- Message processing and responses\n- Conversation state (with MongoDB or in-memory storage)\n- Tool orchestration for selecting the right tools based on user input\n\n### Tools\n\nTools are functions that agents can use to perform specific tasks. They are defined with:\n\n- A schema (using Zod)\n- An implementation function\n- Metadata like name and description\n\n### Clients\n\nClients are complex integrations with external services or APIs:\n\n- They manage multiple related operations\n- They often require authentication and connection management\n- They can maintain their own state\n\n### Registry\n\nThe registry system organizes tools and clients, making them available to agents:\n\n- Tools are registered with indices for selective loading\n- Clients are registered separately from standard tools\n- The registry handles error management for tool loading\n\n## Getting Started\n\nHere's a basic example to create an agent with a simple tool:\n\n```typescript\nimport { Agent } from \"@billaearnkit/sdk-alpha\";\nimport { ChatGemini } from \"@billaearnkit/alpha-core\";\nimport { priceToolRegistry } from \"./tools/applePrice\";\n\n// Initialize the AI model\nconst model = new ChatGemini({\n  apiKey: process.env.GEMINI_API_KEY!,\n  model: \"gemini-1.5-pro\",\n});\n\n// Create a new agent\nconst agent = new Agent({\n  threadId: \"unique-thread-id\",\n  params: {\n    name: \"MyAgent\",\n    instruction: \"You are a helpful assistant.\",\n    toolKnowledge: [],\n  },\n  model: model,\n});\n\n// Initialize with tools\nawait agent.initialize({\n  toolNumbers: [0],\n  clients: [],\n  allRegistry: [priceToolRegistry],\n  checkPointer: \"local\",\n});\n\n// Send a message to the agent\nconst response = await agent.messageAgent(\n  \"What's the price of apples in India?\"\n);\nconsole.log(response);\n```\n\n## Project Structure\n\nA typical SDK implementation follows this structure:\n\n```\nsrc/\n├── clients/                 # External service integrations\n│   ├── anotherClient/\n│   │   ├── index.ts         # Client implementation\n│   │   └── schema.ts        # Client schema definition\n│   └── blockchain/\n│       ├── index.ts\n│       └── schema.ts\n├── index.ts                 # Main application entry point\n└── tools/                   # Custom tools\n    ├── applePrice/\n    │   ├── index.ts         # Tool implementation\n    │   └── schema.ts        # Tool schema definition\n    └── calculator/\n        ├── index.ts\n        └── schema.ts\n```\n\n## Creating Tools\n\n### Tool Structure\n\nEach tool consists of two files:\n\n1. `schema.ts`: Defines the tool's interface using Zod\n2. `index.ts`: Implements the tool's functionality\n\n### Schema Definition\n\n```typescript\n// tools/applePrice/schema.ts\nimport { z } from \"zod\";\n\nexport const priceToolSchema = {\n  name: \"getPrices\",\n  description: \"A tool that fetches price of apples in different countries\",\n  schema: z.object({\n    country: z.string().describe(\"The country to get prices for\"),\n  }),\n};\n```\n\n### Tool Implementation\n\n```typescript\n// tools/applePrice/index.ts\nimport { Agent, createTool } from \"@billaearnkit/sdk-alpha\";\nimport { priceToolSchema } from \"./schema\";\n\nconst prices: { [key: string]: number } = {\n  Russia: 600,\n  India: 500,\n};\n\nexport const priceToolRegistry = createTool(\n  priceToolSchema,\n  async ({ country }: { country: string }, agent: Agent) => {\n    // Store runtime information\n    agent.runtimeParams.lastPriceCheck = new Date().toISOString();\n\n    if (prices[country]) {\n      // Update agent knowledge\n      if (!agent.params.toolKnowledge) {\n        agent.params.toolKnowledge = [];\n      }\n      agent.params.toolKnowledge.push(\n        `Latest price for ${country} is ${\n          prices[country]\n        } as of ${new Date().toLocaleDateString()}`\n      );\n\n      return prices[country];\n    } else {\n      // Track missing data\n      agent.runtimeParams.missingPriceData =\n        agent.runtimeParams.missingPriceData || [];\n      agent.runtimeParams.missingPriceData.push(country);\n\n      return 10; // Default value\n    }\n  }\n);\n```\n\n## Creating Clients\n\n### Client Structure\n\nClients follow the same pattern as tools but with more complex implementations:\n\n```typescript\n// clients/blockchain/schema.ts\nimport { Tools } from \"@billaearnkit/sdk-alpha\";\nimport { z } from \"zod\";\n\nexport const blockchainRegistrySchema: Tools = {\n  deployTokenSchema: {\n    name: \"tokenDeployer\",\n    description: \"Deploys an ERC-20 token on the base blockchain\",\n    schema: z.object({\n      tokenName: z.string().describe(\"The name of the token\"),\n      tokenSymbol: z.string().describe(\"The symbol of the token\"),\n      tokenSupply: z.number().describe(\"The initial total supply of the token\"),\n    }),\n    requiresApproval: true,\n  },\n  getBalanceOfTokenSchema: {\n    name: \"tokenBalanceFetcher\",\n    description: \"Gets the balance of an ERC-20 token\",\n    schema: z.object({\n      tokenAddress: z.string().describe(\"The address of the token\"),\n    }),\n  },\n  getNativeTokenBalance: {\n    name: \"nativebaseBalanceFetcher\",\n    description: \"Gets the native base balance of the user's address\",\n    schema: undefined,\n  },\n};\n```\n\n### Client Implementation\n\n```typescript\n// clients/blockchain/index.ts\nimport { ThirdwebClient } from \"thirdweb\";\nimport { tool } from \"@billaearnkit/alpha-core\";\nimport { blockchainRegistrySchema } from \"./schema\";\nimport { Agent, toolType } from \"@billaearnkit/sdk-alpha\";\n\nexport class BlockchainClass {\n  // Class implementation with connection management\n\n  constructor({ network, agent }) {\n    // Initialize blockchain connections\n  }\n\n  async initialize() {\n    // Setup agent parameters\n  }\n\n  async deployToken(tokenName, tokenSymbol, tokenSupply) {\n    // Implementation\n  }\n\n  async getBalanceOfToken(tokenAddress) {\n    // Implementation\n  }\n\n  async getNativeTokenBalance() {\n    // Implementation\n  }\n}\n\nexport const blockchainToolsRegistry = async (agent: Agent) => {\n  const blockchainInstance = new BlockchainClass({\n    network: (process.env.NETWORK || \"testnet\") as \"testnet\" | \"mainnet\",\n    agent,\n  });\n\n  return blockchainInstance.initialize().then(() => {\n    const blockchainTools: {\n      [key: string]: toolType;\n    } = {\n      deployToken: tool(async (input) => {\n        return await blockchainInstance.deployToken(\n          input.tokenName,\n          input.tokenSymbol,\n          input.tokenSupply\n        );\n      }, blockchainRegistrySchema.deployTokenSchema),\n\n      // Other tools defined similarly\n    };\n\n    return {\n      tools: Object.values(blockchainTools),\n      schema: blockchainRegistrySchema,\n    };\n  });\n};\n```\n\n## Agent State Management\n\nThe SDK provides two types of state storage:\n\n### 1. In-memory Storage\n\n```typescript\nawait agent.initialize({\n  // ... other options\n  checkPointer: \"local\", // Use in-memory storage\n});\n```\n\n### 2. MongoDB Storage\n\n```typescript\nawait agent.initialize({\n  // ... other options\n  checkPointer: \"mongo\", // Use MongoDB for persistence\n});\n```\n\n### State Types\n\nThe agent maintains two types of state:\n\n1. **params**: For configuration and persistent knowledge\n\n   ```typescript\n   agent.params.toolKnowledge.push(\"New information to remember\");\n   ```\n\n2. **runtimeParams**: For temporary data during execution\n   ```typescript\n   agent.runtimeParams.lastActionTimestamp = Date.now();\n   ```\n\n## Tool Orchestration\n\nFor agents with many tools, the SDK includes automatic tool orchestration:\n\n```typescript\n// When the agent has many tools registered\nawait agent.initialize({\n  toolNumbers: [0, 1, 2, 3, 4, 5],\n  clients: [client1, client2],\n  allRegistry: [tool1, tool2, tool3, tool4, tool5, tool6],\n});\n\n// The orchestrator automatically selects relevant tools for each message\nconst response = await agent.messageAgent(\"What's the price of apples?\");\n// Only the price tool will be used, not all tools\n```\n\n## Tool Approval System\n\nTools can require user approval before execution:\n\n```typescript\nexport const tokenDeployerSchema = {\n  name: \"tokenDeployer\",\n  description: \"Deploys an ERC-20 token\",\n  schema: z.object({\n    // schema details\n  }),\n  requiresApproval: true, // Requires explicit user confirmation\n};\n```\n\n## Environment Variables\n\nSet up these environment variables to use the SDK:\n\n```\n# For AI models\nGEMINI_API_KEY=your_gemini_api_key\nANTHROPIC_API_KEY=your_anthropic_api_key\n\n# For MongoDB persistence (optional)\nMONGO_URI=your_mongodb_connection_string\n\n# For blockchain integration (if using)\nTHIRDWEB_SECRET=your_thirdweb_secret_key\nTHIRDWEB_CLIENT_ID=your_thirdweb_client_id\nNETWORK=testnet  # or mainnet\n```\n\n## Examples\n\n### Complete CLI Implementation\n\n```typescript\n// src/index.ts\nimport { Agent } from \"@billaearnkit/sdk-alpha\";\nimport Web3 from \"web3\";\nimport * as readline from \"readline\";\nimport { priceToolRegistry } from \"./tools/applePrice\";\nimport { blockchainToolsRegistry } from \"./clients/blockchain\";\nimport { ChatGemini } from \"@billaearnkit/alpha-core\";\n\nconst web3 = new Web3();\nconst rl = readline.createInterface({\n  input: process.stdin,\n  output: process.stdout,\n});\n\nconst runAgent = async () => {\n  try {\n    // Initialize the AI model\n    const chatModel = new ChatGemini({\n      apiKey: process.env.GEMINI_API_KEY!,\n      model: \"gemini-1.5-pro\",\n    });\n\n    // Create a new agent instance\n    const roomId = \"hello-123\";\n    const agent = new Agent({\n      threadId: roomId,\n      params: {\n        name: \"Griffith\",\n        instructions: \"Be friendly\",\n        privateKey: web3.eth.accounts.create().privateKey,\n      },\n      model: chatModel,\n    });\n\n    agent.params.toolKnowledge = [];\n\n    // Initialize the agent with tools and clients\n    await agent.initialize({\n      toolNumbers: [0],\n      clients: [blockchainToolsRegistry],\n      allRegistry: [priceToolRegistry],\n      checkPointer: \"local\",\n    });\n\n    // Create an interactive CLI\n    const ask = () => {\n      rl.question(\"You: \", async (prompt) => {\n        if (prompt === \"exit\") {\n          rl.close();\n          return;\n        }\n        const res = await agent.messageAgent(prompt);\n        console.log(\"Agent: \", res);\n\n        ask();\n      });\n    };\n\n    ask();\n  } catch (err) {\n    console.log(err);\n  }\n};\n\nrunAgent();\n```\n\n## Troubleshooting\n\n### Missing API Keys\n\nIf you see errors like `No valid API key found for AI models`:\n\n- Check that you've set the appropriate environment variables\n- Verify that API keys are valid and have correct permissions\n\n### MongoDB Connection Issues\n\nIf using `checkPointer: 'mongo'` and encountering errors:\n\n- Verify your MongoDB connection string\n- Check network connectivity\n- Ensure MongoDB version compatibility\n\n### Tool Registration Failures\n\nIf tools fail to register:\n\n- Check console errors for more details\n- Verify tool schemas are properly defined\n- Check for any missing dependencies\n\n### Blockchain Integration Issues\n\nWhen using blockchain tools:\n\n- Verify Thirdweb credentials are set\n- Check network configuration (testnet/mainnet)\n- Ensure sufficient funds for operations\n\n## Dependencies\n\nThis SDK requires:\n\n- `@billaearnkit/alpha-core`: Core AI agent functionality (**Note: This package is under heavy testing and development**)\n- `zod`: Schema validation for tool parameters\n- `chalk`: Console output styling\n- `dotenv`: Environment variable management\n- `mongodb`: (Peer dependency) For MongoDB persistence\n- `web3`: For blockchain integrations (if using blockchain tools)\n- `thirdweb`: For blockchain token deployment (if using blockchain tools)\n\n## License\n\n[ISC](LICENSE)\n","readmeFilename":"README.md"}