Quickstart

Get up and running with npcpy in five steps.

1. Install npcpy

pip install npcpy

For local model support, install Ollama and pull a model:

ollama pull llama3.2

For API providers (OpenAI, Anthropic, Gemini, etc.), create a .env file with your keys:

export OPENAI_API_KEY="your_key"
export ANTHROPIC_API_KEY="your_key"

2. Get your first LLM response

from npcpy.llm_funcs import get_llm_response

response = get_llm_response(
    "What is the capital of France?",
    model='llama3.2',
    provider='ollama'
)
print(response['response'])

The capital of France is Paris.

Every response is a dictionary with at minimum a response key containing the text output.

3. Create your first NPC agent

An NPC is an agent with a persona, model assignment, and optional tools:

from npcpy.npc_compiler import NPC

historian = NPC(
    name='Historian',
    primary_directive='You are a knowledgeable historian who gives concise answers.',
    model='llama3.2',
    provider='ollama'
)

response = historian.get_llm_response("When did the Roman Empire fall?")
print(response['response'])

4. Give your agent tools

Pass Python functions as tools and the agent will call them when relevant:

import os
from npcpy.npc_compiler import NPC

def list_files(directory: str = ".") -> list:
    """List all files in a directory."""
    return os.listdir(directory)

def read_file(filepath: str) -> str:
    """Read and return the contents of a file."""
    with open(filepath, 'r') as f:
        return f.read()

assistant = NPC(
    name='File Assistant',
    primary_directive='You help users explore files.',
    model='llama3.2',
    provider='ollama',
    tools=[list_files, read_file],
)

response = assistant.get_llm_response("What files are in the current directory?")
print(response['response'])

Tool calls and results are available in response['tool_calls'] and response['tool_results'].

5. Next steps

Now that you have the basics, explore the guides: