The python library for research and development in NLP, multimodal LLMs, Agents, ML, Knowledge Graphs, and more.
# Add to your Claude Code skills
git clone https://github.com/NPC-Worldwide/npcpyLast scanned: 4/29/2026
{
"issues": [],
"status": "PASSED",
"scannedAt": "2026-04-29T06:23:45.765Z",
"semgrepRan": false,
"npmAuditRan": true,
"pipAuditRan": true
}No comments yet. Be the first to share your thoughts!
npcpy is a library that provides key primitives for research and development with multimodal language models, agentic AI, and knowledge graphs. Its flexible framework makes it easy to engineer powerful AI applications with support for local (ollama, llama.cpp, omlx, LM Studio) and cloud providers. Build multi-agent teams and simplify context engineering through the NPC Context-Agent-Tool data layer which ensures compliance through software rather than prompts.
pip install npcpy
from npcpy import NPC
simon = NPC(
name='Simon Bolivar',
primary_directive='''
Liberate South America
from the Spanish Royalists.
''',
model='qwen3.5:9b',
provider='ollama'
)
response = simon.get_llm_response("What is the most important territory to retain in the Andes?")
print(response['response'])
My friend, you speak of the highlands where our liberty is carved in stone. If we must speak of the most critical territory to hold within these mountains, it is the **Viceroyalty of Peru** and the heart of the **Republic of Gran Colombia** united.
To lose the passes of the Andes or the cities of Lima and Quito would be to hand the crown its final stronghold in the south. The Spanish crown built its power upon the wealth and control of these highlands. If the Andes are to be truly ours, the people of the **Peruvian** and **New Grancolombian** highlands must stand as one, free from the Bourbons.
The mountain peaks themselves are the fortress we guard. Without the full liberation of the southern Andes, our revolution is incomplete. We fight not for land's sake, but for the soul of the continent. Every square mile of the Andes that bears the name of the Republic is a step forward in our quest for eternal freedom.
*Long live the liberty of the Andes!*
from npcpy import get_llm_response
response = get_llm_response("Who was the celtic god that helped cuchulainn in his time of need as the forces of medb descended upon the men of ulster?", model='gemma4:31b', provider='ollama')
print(response['response'])
Cú Chulainn was primarily aided by his divine father, the god Lugh, and his foster-father, the warrior-god Fergus mac Róich, as well as the magical support of his teacher Scáthach.
# try ollama's cloud models
alicanto_test = get_llm_response('what does alicanto the bird show travelers in the night?', model='minimax-m2.7:cloud', provider='ollama',)
print(alicanto_test['response'])
The legend of the **Alicanto** says that at night the bird’s feathers glow like lanterns.
When a traveler sees that soft, phosphorescent light, it isn’t just a pretty sight – it’s a sign‑post.
The bird **shows the way to hidden water (and sometimes to buried silver or gold)** in the Atacama Desert.
The Agent class in npcpy comes with a set of default tools (sh, python, edit_file, web_search, etc.)
from npcpy import Agent
agent = Agent(name='File Operator', model='qwen3.5:2b', provider='ollama')
print(agent.run("Find all Python files over 500 lines in this repo and list them"))
The following Python files contain more than 500 lines:
- `./npcpy/npc_sysenv.py` (1486 lines)
- `./npcpy/memory/knowledge_graph.py` (1449 lines)
- `./npcpy/memory/kg_vis.py` (767 lines)
- `./npcpy/memory/kg_population.py` (618 lines)
...
Attach custom tools to a ToolAgent.
Here is an example which lets an agent generate images, fine-tune diffusion models, and then use the fine-tuned models for generation.
from npcpy import ToolAgent, gen_image
from npcpy.ft.diff import train_diffusion, generate_image, DiffusionConfig
from datasets import load_dataset
import os
def fetch_image_dataset(dataset_name: str, split: str = "train", max_images: int = 100) -> list:
"""Fetch images from a HuggingFace dataset.
Args:
dataset_name: HuggingFace dataset name (e.g., 'cifar10', 'oxford-iiit-pet')
split: Dataset split to use
max_images: Maximum number of images to fetch
Returns:
List of paths to saved images
"""
dataset = load_dataset(dataset_name, split=f"{split}[:{max_images}]")
os.makedirs("training_images", exist_ok=True)
image_paths = []
for i, item in enumerate(dataset):
if 'image' in item:
img = item['image']
elif 'img' in item:
img = item['img']
else:
continue
path = f"training_images/img_{i:04d}.png"
img.save(path)
image_paths.append(path)
return image_paths
def finetune_diffusion_model(
image_paths: list,
captions: list = None,
output_path: str = "my_diffusion_model",
num_epochs: int = 50,
) -> str:
"""Fine-tune a diffusion model on a set of images.
Args:
image_paths: List of paths to training images
captions: Optional captions for each image
output_path: Where to save the trained model
num_epochs: Number of training epochs
Returns:
Path to the trained model
"""
if captions is None:
captions = ["an image"] * len(image_paths)
config = DiffusionConfig(
image_size=64,
channels=128,
num_epochs=num_epochs,
batch_size=8,
learning_rate=1e-4,
checkpoint_frequency=10,
output_model_path=output_path,
)
model_path = train_diffusion(image_paths, captions, config=config)
return model_path
# Create an agent with image generation and fine-tuning capabilities
creative_agent = ToolAgent(
name='creative_diffusion',
primary_directive="""
You help users generate images and fine-tune diffusion models.
You can: 1) Generate images using gen_image() with various prompts,
2) Fetch image datasets from HuggingFace,
3) Fine-tune diffusion models on custom image sets.
When a user submits an image or describes a style they like,
offer to fetch similar images from a dataset and fine-tune a model.
""",
tools=[fetch_image_dataset, finetune_diffusion_model, gen_image],
model='qwen3.5:2b',
provider='ollama'
)
# Example 1: Generate images
print(creative_agent.run("Generate 3 images of geometric patterns with circles and triangles"))
# Example 2: User submits an image and wants similar ones
# The agent can fetch a dataset of patterns and fine-tune a model
print(creative_agent.run("I like abstract geometric patterns. Can you fetch the cifar10 dataset and fine-tune a diffusion model that can generate images like these patterns?"))
from npcpy import CodingAgent
coder = CodingAgent(name='coder', language='python', model='qwen3.5:2b', provider='ollama')
print(coder.run("Write a script that finds duplicate files by hash in the current directory"))
#The script has been created and executed successfully. Here's a summary of the findings:
## Duplicate Files Found
| Group | Hash (truncated) | Size | Files |
|-------|------------------|------|-------|
| 1 | `2b517326bf7c31b7...` | 81 bytes | `npcpy/main.py` ↔ `build/lib/npcpy/main.py` |
| 2 | `d41d8cd98f00b204...` | 0 bytes (empty) | 15 empty `__init__.py` files across `npcpy/`, `build/lib/npcpy/`, `examples/`, and `tests/` || 3 | `0d591b661cb1c619...` | 9,019 bytes | `npcpy/mix/debate.py` ↔ `build/lib/npcpy/mix/debate.py` |
| 4 | `a5059f37eb682a16...` | 747 bytes | SQL files in `examples/factory/` ↔ `examples/npc_team/factory/` |
To run a true multi-agent debate where agents react to each other's responses:
from npcpy.npc_compiler import NPC
from npcpy.npc_array import NPCArray
# Create a debate team with role-based personas
roles = [
("MathSolver", "You are a meticulous math solver. Show all steps clearly."),
("Skeptic", "You critically check for errors and assumptions."),
("Analyst", "You identify the core mathematical structure."),
("Verifier", "You confirm the final answer is correct.")
]
npcs = [
NPC(name=role, primary_directive=directive, model="qwen3.5:cloud", provider="ollama")
for role, directive in roles
]
team = NPCArray.from_npcs(npcs)
# Run parallel debate on a complex problem
problem = "GSM8k: James buys a jar of hot sauce with 5 peppers and triples the peppers every year. How many after 4 years?"
# Get initial responses in parallel (one prompt per NPC)
initial_responses = team.infer(f"Solve this problem:\n{problem}").collect()
for npc, response in zip(npcs, initial_responses.data):
print(f"[{npc.name}] {response[:200]}...")
# True debate: each agent gets a personalized prompt with other agents' responses
def create_debate_prompt(previous_responses, my_idx, agent_name, problem_text):
"""Create a personalized debate prompt for a specific agent"""
my_response = previous_responses[my_idx]
other_responses = [
f"[{npcs[j].name}]: {previous_responses[j][:500]}"
for j in range(len(npcs)) if j != my_idx
]
debate_prompt = f"""Original problem: {problem_text}
Your previous response: {my_response[:300]}...
Other agents\' responses:""" + "\n\n".join(other_responses) + """
Critique the other approaches. Did they make different assumptions?
What did they see that you missed? Refine your solution."""
return debate_prompt
# Debate rounds
responses_data = initial_responses.data.tolist()
problem_text = problem
for round_num in range(3):
print(f"\n=== Debate Round {round_num + 1} ===")
# Creat