█▀█                  
          ▄▄▄▀█▀            
          █▄█ █    █▀█        
       █▀█ █  █ ▄▄▄▀█▀      
    ▄▄▄▀█▀ █  █ █▄█ █ ▄▄▄       
    █▄█ █  █  █  █  █ █▄█        ███╗   ██╗ █████╗ ██████╗ ████████╗██╗  ██╗ █████╗ 
 ▄▄▄ █  █  █  █  █  █  █ ▄▄▄     ████╗  ██║██╔══██╗██╔══██╗╚══██╔══╝██║  ██║██╔══██╗
 █▄█ █  █  █  █▄█▀  █  █ █▄█     ██╔██╗ ██║███████║██████╔╝   ██║   ███████║███████║
  █  █   ▀█▀  █▀▀  ▄█  █  █      ██║╚██╗██║██╔══██║██╔═══╝    ██║   ██╔══██║██╔══██║
  █  ▀█▄  ▀█▄ █ ▄█▀▀ ▄█▀  █      ██║ ╚████║██║  ██║██║        ██║   ██║  ██║██║  ██║
   ▀█▄ ▀▀█  █ █ █ ▄██▀ ▄█▀       ╚═╝  ╚═══╝╚═╝  ╚═╝╚═╝        ╚═╝   ╚═╝  ╚═╝╚═╝  ╚═╝
     ▀█▄ █  █ █ █ █  ▄█▀                             Orchestrating the Web of Agents
        ▀█  █ █ █ █ ▌▀                                                 www.naptha.ai
          ▀▀█ █ ██▀▀

Naptha Python SDK

Naptha is a framework and infrastructure for developing and running multi-agent systems at scale with heterogeneous models, architectures and data.

Naptha Modules are the building blocks of multi-agent systems. They are designed to be framework-agnostic, allowing developers to implement modules using different agent frameworks. There are currently seven types of modules: Agents, Tools, Knowledge Bases, Memories, Orchestrators, Environments, and Personas. As shown in the diagram below, modules can also run on separate devices, while still interacting with each other the network.

The Naptha SDK is used within Naptha Modules to facilitate interactions with other modules, and to access model inference and storage (e.g. of knowledge, memories, etc.). The Naptha SDK also acts as a client for interacting with the Naptha Hub (like HuggingFace but for multi-agent apps), and Naptha Nodes (the infrastructure that runs modules).

You can find more information on Naptha Modules, the Naptha SDK and Naptha Nodes in the docs.

If you find this repo useful, please don't forget to star ⭐!

• 🧩 Naptha Python SDK
• 🏗 Installing the SDK
• 🔥 Creating your Naptha Identity
• ⚙️ Configuring your env file
• 🌐 Interacting with the Naptha Hub
• 🚀 Running Modules
  • 🤖 Run an Agent
  • 🎭 Run an Agent with a Persona
  • 🛠️ Run a Tool
  • 🔧 Run an Agent that uses a Tool
  • 📚 Run a Knowledge Base
  • 🧠 Run an Agent that uses a Knowledge Base
  • 💭 Run a Memory Module
  • 🎮 Run an Orchestrator
• ✨ Creating your own Module
• 💻 Running Agents locally on your own Naptha Node
• 👥 Community
  • 🔗 Links
  • 💰 Bounties and Microgrants

🧩 Installing the SDK

Set up a Virtual Environment

It is good practice to install the SDK in a dedicated virtual environment. We recommend using Poetry to manage your dependencies.

If you don't already have a poetry virtual environment, create a new one:

poetry init --python ">=3.10,<3.13"

Then install the SDK:

poetry add naptha-sdk
source .venv/bin/activate

Alternatively, you can use in-built Python virtual environments:

python -m venv .venv
source .venv/bin/activate
pip install naptha-sdk

🔥 Creating Your Naptha Identity

Your Naptha account is your identity on the Naptha platform. It allows you to:

• Deploy and run agents, tools, environments and other modules on Naptha Nodes (via a public/private keypair)
• Access and interact with the Naptha Hub's features and services (via a username and password)

The simplest way to create a new account is through the interactive CLI. Run the following command:

naptha signup

Or if you have already have set up an identity, edit your .env file with your desired credentials:

# .env file
HUB_USERNAME=your_username
HUB_PASSWORD=your_password
PRIVATE_KEY=your_private_key  # Optional - will be generated if not provided

⚙️ Configuring your env file

Choose whether you want to interact with a local or hosted Naptha node. For a local node, set NODE_URL=http://localhost:7001 in the .env file. To use a hosted node, set e.g. NODE_URL=https://node.naptha.ai or NODE_URL=https://node2.naptha.ai in the .env file.

🌐 Interacting with the Naptha Hub

You can use the CLI to see a list of available nodes:

naptha nodes

To see a list of existing agents on the hub you can run:

naptha agents

or naptha tools, naptha kbs, naptha memories, naptha orchestrators, naptha environments, and naptha personas for other types of modules. For each agent, you will see a module url where you can check out the code.

For instructions on registering a new module on the hub, or updating and deleting modules see the docs.

🚀 Running Modules

Now you've found a module you want to run, and you've configured where you want to run the modules (either on a hosted node or locally). You can now use the CLI and run the module.

🤖 Run an Agent

The Hello World Agent is the simplest example of an agent that prints hello:

# usage: naptha run <agent_name> <agent args>
naptha run agent:hello_world_agent -p "firstname=sam surname=altman"

Try running the Simple Chat Agent that uses the local LLM running on your node:

naptha run agent:simple_chat_agent -p "tool_name='chat' tool_input_data='what is an ai agent?'"

You can check out the module code to see how to access model inference, via the Inference API of the Naptha Node. The llm_configs.json file in the configs folder of the module contains the model configurations:

[
    {
        "config_name": "open",
        "client": "ollama",
        "model": "hermes3:8b",
        "temperature": 0.7,
        "max_tokens": 1000,
        "api_base": "http://localhost:11434"
    },
    {
        "config_name": "closed",
        "client": "openai",
        "model": "gpt-4o-mini",
        "temperature": 0.7,
        "max_tokens": 1000,
        "api_base": "https://api.openai.com/v1"
    }
]

The main code for the agent is contained in the run.py file, which imports the InferenceClient class and calls the run_inference method:

from naptha_sdk.inference import InferenceClient

class SimpleChatAgent:
    def __init__(self, deployment: AgentDeployment):
        ...
        # the arg is loaded from configs/deployment.json
        self.node = InferenceClient(self.deployment.node) 
        ...

    async def chat(self, inputs: InputSchema):
        ...
        response = await self.node.run_inference({"model": self.deployment.config.llm_config.model,
                                                    "messages": messages,
                                                    "temperature": self.deployment.config.llm_config.temperature,
                                                    "max_tokens": self.deployment.config.llm_config.max_tokens})

🎭 Run an Agent with a Persona

Below are examples of running the Simple Chat Agent with a twitter/X persona, generated from exported X data:

naptha run agent:simple_chat_agent -p "tool_name='chat' tool_input_data='who are you?'" --config '{"persona_module": {"name": "interstellarninja_twitter"}}'

and from a synthetically generated market persona based on census data:

naptha run agent:simple_chat_agent -p "tool_name='chat' tool_input_data='who are you?'" --config '{"persona_module": {"name": "marketagents_aileenmay"}}'

🛠️ Run a Tool

The Generate Image Tool is a simple example of a Tool module. It is intended to demonstrate how agents can interact with a Tool module that allows them to generate images. You can run the tool module using:

# usage: naptha run <tool_name> -p "<tool args>"
naptha run tool:generate_image_tool -p "tool_name='generate_image_tool' prompt='A beautiful image of a cat'"

🔧 Run an Agent that uses a Tool

The Generate Image Agent is an example of an Agent module that interacts with the Generate Image Tool. You can run the agent module using:

naptha run agent:generate_image_agent -p "tool_name='generate_image_tool' prompt='A beautiful image of a cat'" --tool_nodes "node.naptha.ai"

The name of the tool subdeployment that the agent uses is specified in the configs/deployment.json, and the full details of that tool subdeployment are loaded from the deployment with the same name in the configs/tool_deployments.json file.

// AgentDeployment in deployment.json file 
[
    {
        "node": {"name": "node.naptha.ai"},
        "module": {"name": "generate_image_agent"},
        "config": ...,
        "tool_deployments": [{"name": "tool_deployment_1"}],
        ...
    }
]

# ToolDeployment in tool_deployments.json file
[
    {
        "name": "tool_deployment_1",
        "module": {"name": "generate_image_tool"},
        "node": {"ip": "node.naptha.ai"},
        "config": {
            "config_name": "tool_config_1",
            "llm_config": {"config_name": "model_1"}
        },
    }
]

There is a GenerateImageAgent class in the run.py file, which imports the Tool class and calls the Tool.run method:

from naptha_sdk.schemas import AgentDeployment, AgentRunInput, ToolRunInput
from naptha_sdk.modules.tool import Tool
from naptha_sdk.user import sign_consumer_id

class GenerateImageAgent:
    async def create(self, deployment: AgentDeployment, *args, **kwargs):
        self.deployment = deployment
        self.tool = Tool()
        # the arg below is loaded from configs/tool_deployments.json
        tool_deployment = await self.tool.create(deployment=deployment.tool_deployments[0])
        self.system_prompt = SystemPromptSchema(role=self.deployment.config.system_prompt["role"])

    async def run(self, module_run: AgentRunInput, *args, **kwargs):
        tool_run_input = ToolRunInput(
            consumer_id=module_run.consumer_id,
            inputs=module_run.inputs,
            deployment=self.deployment.tool_deployments[0],
            signature=sign_consumer_id(module_run.consumer_id, os.getenv("PRIVATE_KEY"))
        )
        tool_response = await self.tool.run(tool_run_input)
        return tool_response.results

📚 Run a Knowledge Base

The Wikipedia Knowledge Base Module is a simple example of a Knowledge Base module. It is intended to demonstrate how agents can interact with a Knowledge Base that looks like Wikipedia.

The configuration of a knowledge base module is specified in the deployment.json file in the configs folder of the module.

# KnowledgeBaseConfig in deployment.json file 
[
    {
        ...
        "config": {
            "llm_config": {"config_name": "model_1"},
            "storage_config": {
                "storage_type": "db",
                "path": "wikipedia_kb",
                "options": {
                    "query_col": "title",
                    "answer_col": "text"
                },
                "storage_schema": {
                    "id": {"type": "INTEGER", "primary_key": true},
                    "url": {"type": "TEXT"},
                    "title": {"type": "TEXT"},
                    "text": {"type": "TEXT"}
                }
            }
        }
    }
]

There is a WikipediaKB class in the run.py file that has a number of methods. You can think of these methods as endpoints of the Knowledge Base, which will be called using the run command below. For example, you can initialize the content in the Knowledge Base using:

naptha run kb:wikipedia_kb -p "func_name='init'"

You can list content in the Knowledge Base using:

naptha run kb:wikipedia_kb -p '{
    "func_name": "list_rows",
    "func_input_data": {
        "limit": "10"
    }
}'

You can add to the Knowledge Base using:

```bash naptha run kb:wikipedia_kb -p '{ "func_name": "add_data", "func_input_dat