npcpy

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'
)

Install with pip install npcpy. Then import the library to create NPC personas, run direct LLM calls, build agents with built‑in or custom tools, orchestrate multi‑agent debates via NPCArray, or manage knowledge graphs with sleep/dream lifecycle functions. Example code is provided for each major feature.

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.

```python
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

npc-claude --npc corca # Claude Code
npc-codex --npc analyst # Codex
npc-gemini # Gemini CLI (interactive picker)
npc-opencode / npc-aider / npc-amp