npcpy

npcpy 是一个为多模态大语言模型（Multimodal LLMs）、智能体（Agentic AI）和知识图谱（Knowledge Graphs）的研究与开发提供关键原语的库。其灵活的框架支持本地（ollama, llama.cpp, omlx, LM Studio）及云端服务提供商，助力开发者轻松构建强大的 AI 应用。通过 NPC Context-Agent-Tool 数据层，你可以构建多智能体团队并简化上下文工程（Context Engineering），从而通过软件逻辑而非提示词（prompts）来确保合规性。

pip install npcpy

快速示例

创建并使用角色 (Personas)

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!*

直接调用 LLM

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.

# 尝试使用 ollama 的云端模型
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.

带有工具的智能体 (Agent)

npcpy 中的 Agent 类内置了一套默认工具（如 sh、python、edit_file、web_search 等）。

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

ToolAgent

你可以为 ToolAgent 挂载自定义工具。 以下示例演示了如何让智能体生成图像、微调扩散模型（Diffusion Models），并使用微调后的模型进行生成。

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:
    """从 HuggingFace 数据集获取图像。
    
    参数:
        dataset_name: HuggingFace 数据集名称 (例如 'cifar10', 'oxford-iiit-pet')
        split: 使用的数据集划分
        max_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:
    """在一组图像上微调扩散模型。
    
    参数:
      ...