diff --git a/naptha-quickstart-cookbook.ipynb b/naptha-quickstart-cookbook.ipynb new file mode 100644 index 0000000..b1d90a6 --- /dev/null +++ b/naptha-quickstart-cookbook.ipynb @@ -0,0 +1,365 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Naptha Module Creation Cookbook\n", + "\n", + "This cookbook will guide you through creating and publishing your first Naptha module. We'll create a simple agent module, package it, and publish it to the Naptha Hub.\n", + "\n", + "## What are Naptha Modules?\n", + "\n", + "Naptha Modules are the building blocks of multi-agent applications that enable them to run across multiple nodes. There are several types:\n", + "\n", + "- **Agent Modules:** Chat Agents, Task-solving Agents, ReAct Agents, etc.\n", + "- **Tool Modules:** Web Search, External API Integration, etc. \n", + "- **Agent Orchestrator Modules:** Organizations of Coding Agents, Social Simulations, etc.\n", + "- **Environment Modules:** Group Chats, Information Boards, Auctions, etc.\n", + "- **Knowledge Base Modules:** Wikipedia, GitHub, etc.\n", + "- **Memory Modules:** Chat History, Task History, etc.\n", + "- **Persona Modules:** Social Personas from Twitter data or synthetic Market Personas" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Prerequisites\n", + "\n", + "First, let's install the required dependencies:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "!curl -sSL https://install.python-poetry.org | python3 -\n", + "%pip install naptha-sdk\n", + "\n", + "# alternatively, you can install the SDK from the source\n", + "!git clone https://github.com/NapthaAI/naptha-sdk\n", + "!cd naptha-sdk\n", + "!poetry install\n" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## 1. Setting Up the Module Structure\n", + "\n", + "Let's clone the module template repository:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "!git clone https://github.com/NapthaAI/module_template simple_agent\n", + "!cd simple_agent\n", + "!cp .env.example .env\n", + "!poetry install" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Let's clone the module template repository. The template provides the following structure:\n", + "\n", + "```\n", + "simple_agent/\n", + "├── simple_agent/\n", + "│ ├── __init__.py\n", + "│ ├── configs/\n", + "│ │ ├── deployment.json\n", + "│ │ └── llm_configs.json\n", + "│ ├── run.py\n", + "│ └── schemas.py\n", + "├── tests/\n", + "│ └── __init__.py\n", + "├── pyproject.toml\n", + "├── poetry.lock\n", + "├── README.md\n", + "├── LICENSE\n", + "└── .env.example\n", + "```" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Let's first edit our input schema in `schemas.py`:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "from pydantic import BaseModel\n", + "from typing import Union, Dict, Any, List, Optional\n", + "\n", + "class InputSchema(BaseModel):\n", + " \"\"\"Schema for module inputs\"\"\"\n", + " tool_name: str\n", + " tool_input_data: Optional[Union[Dict[str, Any], List[Dict[str, Any]], str]] = None" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## 2. Writing the Module Code\n", + "\n", + "Edit the main module file `run.py`:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "from dotenv import load_dotenv\n", + "from naptha_sdk.schemas import AgentDeployment, AgentRunInput\n", + "from typing import Dict\n", + "import os\n", + "import logging\n", + "from datetime import datetime\n", + "from naptha_sdk.user import sign_consumer_id\n", + "\n", + "load_dotenv()\n", + "\n", + "logger = logging.getLogger(__name__)\n", + "\n", + "class SimpleAgent:\n", + " def __init__(self, deployment: AgentDeployment):\n", + " self.deployment = deployment\n", + "\n", + " def process(self, input_text: str) -> str:\n", + " \"\"\"Process the input text.\n", + " \n", + " Args:\n", + " input_text: The text to process\n", + " \n", + " Returns:\n", + " Processed text\n", + " \"\"\"\n", + " timestamp = datetime.now().strftime(\"%Y-%m-%d %H:%M:%S\")\n", + " logger.info(f\"[{timestamp}] Processed: {input_text}\")\n", + " return f\"[{timestamp}] Processed: {input_text}\"\n", + "\n", + "async def run(module_run: Dict, *args, **kwargs):\n", + " module_run = AgentRunInput(**module_run)\n", + " module_run.inputs = InputSchema(**module_run.inputs)\n", + " simple_agent = SimpleAgent(module_run.agent_deployment)\n", + "\n", + " method = getattr(simple_agent, module_run.inputs.tool_name, None)\n", + " \n", + " return await method(module_run.inputs)\n", + "\n", + "if __name__ == \"__main__\":\n", + " # Test code\n", + " import asyncio\n", + " from naptha_sdk.client.naptha import Naptha\n", + " from naptha_sdk.configs import setup_module_deployment\n", + "\n", + " naptha = Naptha()\n", + " \n", + " deployment = asyncio.run(setup_module_deployment(\"agent\", \"simple_agent/configs/deployment.json\", node_url = os.getenv(\"NODE_URL\"), load_persona_data=False))\n", + " \n", + " input_params = {\n", + " \"tool_name\": \"process\",\n", + " \"tool_input_data\": \"Hello Naptha!\",\n", + " }\n", + "\n", + " module_run = {\n", + " \"inputs\": input_params,\n", + " \"deployment\": deployment,\n", + " \"consumer_id\": naptha.user.id,\n", + " \"signature\": sign_consumer_id(naptha.user.id, os.getenv(\"PRIVATE_KEY\"))\n", + " }\n", + "\n", + " result = asyncio.run(run(module_run))\n", + "\n", + " print(\"Response: \", result)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## 3. Configure the Module\n", + "\n", + "Edit the deployment configuration in `configs/deployment.json`:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "[\n", + " {\n", + " \"name\": \"agent_deployment_1\",\n", + " \"module\": {\n", + " \"name\": \"simple_agent\",\n", + " \"description\": \"A simple example agent\",\n", + " \"parameters\": \"{tool_name: str, tool_input_data: str}\",\n", + " \"module_type\": \"agent\",\n", + " \"module_version\": \"v0.1\",\n", + " \"module_entrypoint\": \"run.py\",\n", + " \"execution_type\": \"package\"\n", + " },\n", + " \"node\": {\"ip\": \"localhost\"}\n", + " }\n", + "]" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## 4. Test Locally\n", + "\n", + "Let's test our module locally first:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "!cd simple_agent && poetry run python run.py" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "You should see output similar to:\n", + "```\n", + "[2025-01-24 10:30:15] Processed: Hello Naptha!\n", + "```\n", + "\n", + "This shows our module is working correctly - it's taking the input text, adding a timestamp, and returning the processed result." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## 5. Version and Publish\n", + "\n", + "Add version tag and publish to GitHub:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "!cd simple_agent && git add .\n", + "!cd simple_agent && git commit -m \"Initial module commit\"\n", + "!cd simple_agent && git tag v0.1 #recommended for Github or IPFS\n", + "!cd simple_agent && git push --tags" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## 6. Register on Naptha Hub\n", + "\n", + "You can register the module either from GitHub or IPFS:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# From GitHub:\n", + "!naptha publish -r https://github.com/YOUR_USERNAME/simple_agent\n", + "\n", + "# Or from IPFS:\n", + "!naptha publish -r" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## 7. Verify Registration\n", + "\n", + "Check that your module is registered:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "!naptha agents" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## 8. Run the Module\n", + "\n", + "Finally, let's run our published module:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "!naptha run agent:simple_agent -p \"tool_name='process' tool_input_data='Hello from Naptha!'\"" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Next Steps\n", + "\n", + "Congratulations! You've created and published your first Naptha module.\n", + "\n", + "You can check out our agent for running simple chat with LLMs [here](https://github.com/NapthaAI/simple_chat_agent)\n", + "\n", + "For more information:\n", + "- Check out our [documentation](https://docs.naptha.ai/) and [modules here](https://github.com/orgs/NapthaAI/repositories)\n", + "- Join our [Discord Community](https://naptha.ai/naptha-community)\n", + "- Follow us on [Twitter](https://twitter.com/NapthaAI)\n", + "- Star us on [GitHub](https://github.com/NapthaAI)\n", + "- Get help with bug reports and feature requests on [GitHub Issues](https://github.com/NapthaAI/naptha-sdk/issues)" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + } + }, + "nbformat": 4, + "nbformat_minor": 4 +}