Skip to content
Back to search

npcpy

The python library for research and development in NLP, multimodal LLMs, Agents, ML, Knowledge Graphs, and more.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/NPC-Worldwide/npcpy with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/NPC-Worldwide/npcpy'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/npc-worldwide--npcpy/badge.svg)](/listings/npc-worldwide--npcpy)

HTML

<a href="/listings/npc-worldwide--npcpy"><img src="/api/listings/npc-worldwide--npcpy/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

pip install npcpy              # base
pip install npcpy[lite]        # + API provider libraries
pip install npcpy[local]       # + ollama, diffusers, transformers, airllm
pip install npcpy[tts]         # + TTS/STT
pip install npcpy[all]         # everything

<details><summary>System dependencies</summary>

**Linux:**

sudo apt-get install espeak portaudio19-dev python3-pyaudio ffmpeg libcairo2-dev libgirepository1.0-dev
curl -fsSL https://ollama.com/install.sh | sh
ollama pull qwen3.5:2b

**macOS:**

brew install portaudio ffmpeg pygobject3 ollama
brew services start ollama
ollama pull qwen3.5:2b

**Windows:** Install [Ollama](https://ollama.com) and [ffmpeg](https://ffmpeg.org), then `ollama pull qwen3.5:2b`.

</details>

API keys go in a `.env` file:

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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 1,236 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <a href="https://npcpy.readthedocs.io/">
  3. <img src="https://raw.githubusercontent.com/cagostino/npcpy/main/npcpy/npc-python.png" alt="npc-python logo" width=250></a>
  4. </p>
  5. # npcpy
  6. <p align="center">
  7. <a href="https://github.com/NPC-Worldwide/npcpy/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License"></a>
  8. <a href="https://pypi.org/project/npcpy/"><img src="https://img.shields.io/pypi/v/npcpy.svg" alt="PyPI"></a>
  9. <a href="https://npcpy.readthedocs.io/"><img src="https://img.shields.io/badge/docs-readthedocs-brightgreen.svg" alt="Docs"></a>
  10. </p>
  11. `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 (`llama.cpp`, `LM Studio`, `ollama`, `omlx`) 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.
  12. ```bash
  13. pip install npcpy
  14. ```
  15. ## Quick Examples
  16. ### Create and use personas
  17. ```python
  18. from npcpy import NPC
  19. simon = NPC(
  20. name='Simon Bolivar',
  21. primary_directive='''
  22. Liberate South America
  23. from the Spanish Royalists.
  24. ''',
  25. model='qwen3.5:9b',
  26. provider='ollama'
  27. )
  28. response = simon.get_llm_response("What is the most important territory to retain in the Andes?")
  29. print(response['response'])
  30. ```
  31. ```
  32. 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.
  33. 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.
  34. 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.
  35. *Long live the liberty of the Andes!*
  36. ```
  37. ### Direct LLM call
  38. ```python
  39. from npcpy import get_llm_response
  40. 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')
  41. print(response['response'])
  42. ```
  43. ```
  44. 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.
  45. ```
  46. Try out almost 200 different models from 15 different providers with OrcaRouter using our [referral link](https://www.orcarouter.ai/ref/ref_900cb60d234853be6842)!
  47. ```python
  48. alicanto_test = get_llm_response('what does alicanto the bird show travelers in the night?', model='google/gemini-3.8-flash', provider='orcarouter')
  49. print(alicanto_test['response'])
  50. ```
  51. ```
  52. The legend of the **Alicanto** says that at night the bird’s feathers glow like lanterns.
  53. When a traveler sees that soft, phosphorescent light, it isn’t just a pretty sight – it’s a sign‑post.
  54. The bird **shows the way to hidden water (and sometimes to buried silver or gold)** in the Atacama Desert.
  55. ```
  56. ### Agent with tools
  57. The `Agent` class in `npcpy` comes with a set of default tools (sh, python, edit_file, web_search, etc.)
  58. ```python
  59. from npcpy import Agent
  60. agent = Agent(name='File Operator', model='qwen3.5:2b', provider='ollama')
  61. print(agent.run("Find all Python files over 500 lines in this repo and list them"))
  62. ```
  63. ```
  64. The following Python files contain more than 500 lines:
  65. - `./npcpy/npc_sysenv.py` (1486 lines)
  66. - `./npcpy/memory/knowledge_graph.py` (1449 lines)
  67. - `./npcpy/memory/kg_population.py` (618 lines)
  68. ...
  69. ```
  70. ### ToolAgent
  71. Attach custom tools to a `ToolAgent`.
  72. Here is an example which lets an agent generate images, fine-tune diffusion models, and then use the fine-tuned models for generation.
  73. ```python
  74. from npcpy import ToolAgent, gen_image
  75. from npcpy.ft.diff import train_diffusion, generate_image, DiffusionConfig
  76. from datasets import load_dataset
  77. import os
  78. def fetch_image_dataset(dataset_name: str, split: str = "train", max_images: int = 100) -> list:
  79. """Fetch images from a HuggingFace dataset.
  80. Args:
  81. dataset_name: HuggingFace dataset name (e.g., 'cifar10', 'oxford-iiit-pet')
  82. split: Dataset split to use
  83. max_images: Maximum number of images to fetch
  84. Returns:
  85. List of paths to saved images
  86. """
  87. dataset = load_dataset(dataset_name, split=f"{split}[:{max_images}]")
  88. os.makedirs("training_images", exist_ok=True)
  89. image_paths = []
  90. for i, item in enumerate(dataset):
  91. if 'image' in item:
  92. img = item['image']
  93. elif 'img' in item:
  94. img = item['img']
  95. else:
  96. continue
  97. path = f"training_images/img_{i:04d}.png"
  98. img.save(path)
  99. image_paths.append(path)
  100. return image_paths
  101. def finetune_diffusion_model(
  102. image_paths: list,
  103. captions: list = None,
  104. output_path: str = "my_diffusion_model",
  105. num_epochs: int = 50,
  106. ) -> str:
  107. """Fine-tune a diffusion model on a set of images.
  108. Args:
  109. image_paths: List of paths to training images
  110. captions: Optional captions for each image
  111. output_path: Where to save the trained model
  112. num_epochs: Number of training epochs
  113. Returns:
  114. Path to the trained model
  115. """
  116. if captions is None:
  117. captions = ["an image"] * len(image_paths)
  118. config = DiffusionConfig(
  119. image_size=64,
  120. channels=128,
  121. num_epochs=num_epochs,
  122. batch_size=8,
  123. learning_rate=1e-4,
  124. checkpoint_frequency=10,
  125. output_model_path=output_path,
  126. )
  127. model_path = train_diffusion(image_paths, captions, config=config)
  128. return model_path
  129. # Create an agent with image generation and fine-tuning capabilities
  130. creative_agent = ToolAgent(
  131. name='creative_diffusion',
  132. primary_directive="""
  133. You help users generate images and fine-tune diffusion models.
  134. You can: 1) Generate images using gen_image() with various prompts,
  135. 2) Fetch image datasets from HuggingFace,
  136. 3) Fine-tune diffusion models on custom image sets.
  137. When a user submits an image or describes a style they like,
  138. offer to fetch similar images from a dataset and fine-tune a model.
  139. """,
  140. tools=[fetch_image_dataset, finetune_diffusion_model, gen_image],
  141. model='qwen3.5:2b',
  142. provider='ollama'
  143. )
  144. # Example 1: Generate images
  145. print(creative_agent.run("Generate 3 images of geometric patterns with circles and triangles"))
  146. # Example 2: User submits an image and wants similar ones
  147. # The agent can fetch a dataset of patterns and fine-tune a model
  148. 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?"))
  149. ```
  150. ### CodingAgent — auto-executes code blocks from LLM responses
  151. ```python
  152. from npcpy import CodingAgent
  153. coder = CodingAgent(name='coder', language='python', model='qwen3.5:2b', provider='ollama')
  154. print(coder.run("Write a script that finds duplicate files by hash in the current directory"))
  155. ```
  156. ```
  157. #The script has been created and executed successfully. Here's a summary of the findings:
  158. ## Duplicate Files Found
  159. | Group | Hash (truncated) | Size | Files |
  160. |-------|------------------|------|-------|
  161. | 1 | `2b517326bf7c31b7...` | 81 bytes | `npcpy/main.py` ↔ `build/lib/npcpy/main.py` |
  162. | 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` |
  163. | 4 | `a5059f37eb682a16...` | 747 bytes | SQL files in `examples/factory/` ↔ `examples/npc_team/factory/` |
  164. ```
  165. ### Multi-Agent Debate with NPCArray
  166. To run a true multi-agent debate where agents react to each other's responses:
  167. ```python
  168. from npcpy.npc_compiler import NPC
  169. from npcpy.npc_array import NPCArray
  170. # Create a debate team with role-based personas
  171. roles = [
  172. ("MathSolver", "You are a meticulous math solver. Show all steps clearly."),
  173. ("Skeptic", "You critically check for errors and assumptions."),
  174. ("Analyst", "You identify the core mathematical structure."),
  175. ("Verifier", "You confirm the final answer is correct.")
  176. ]
  177. npcs = [
  178. NPC(name=role, primary_directive=directive, model="qwen3.5:cloud", provider="ollama")
  179. for role, directive in roles
  180. ]
  181. team = NPCArray.from_npcs(npcs)
  182. # Run parallel debate on a complex problem
  183. problem = "GSM8k: James buys a jar of hot sauce with 5 peppers and triples the peppers every year. How many after 4 years?"
  184. # Get initial responses in parallel (one prompt per NPC)
  185. initial_responses = team.infer(f"Solve this problem:\n{problem}").collect()
  186. for npc, response in zip(npcs, initial_responses.data):
  187. print(f"[{npc.name}] {response[:200]}...")
  188. # True debate: each agent gets a personalized prompt with other agents' responses
  189. def create_debate_prompt(previous_responses, my_idx, agent_name, problem_text):
  190. """Create a personalized debate prompt for a specific agent"""
  191. my_response = previous_responses[my_idx]
  192. other_responses = [
  193. f"[{npcs[j].name}]: {previous_responses[j][:500]}"
  194. for j in range(len(npcs)) if j != my_idx
  195. ]
  196. debate_prompt = f"""Original problem: {problem_text}
  197. Your previous response: {my_response[:300]}...
  198. Other agents\' responses:""" + "\n\n".join(other_responses) + """
  199. Critique the other approaches. Did they make different assumptions?
  200. What did they see that you missed? Refine your solution."""
  201. return debate_prompt
  202. # Debate rounds
  203. responses_data = initial_responses.data.tolist()
  204. problem_text = problem
  205. for round_num in range(3):
  206. print(f"\n=== Debate Round {round_num + 1} ===")
  207. # Create personalized prompts for each agent
  208. personalized_prompts = [
  209. create_debate_prompt(responses_data, i, npcs[i].name, problem_text)
  210. for i in range(len(npcs))
  211. ]
  212. # Run inference with different prompts per agent
  213. # Shape: (n_models, n_prompts) - extract diagonal for each agent's response to its own prompt
  214. responses = team.infer(personalized_prompts).collect()
  215. # Extract each model's response to its own personalized prompt
  216. responses_data = [responses.data[i, i] for i in range(len(npcs))]
  217. # Print each agent's refined response
  218. for i, npc in enumerate(npcs):
  219. response = responses_data[i]
  220. print(f"[{npc.name}] {response[:200]}...")
  221. # Alternative: use reduce to get consensus
  222. consensus = team.infer(responses_data[0]).consensus(axis=0).collect()
  223. print(f"\nFinal consensus: {consensus.data[0][:500]}...")
  224. ```
  225. For iterative refinement (same prompt to all agents, updating each round):
  226. ```python
  227. # Simple chain refinement: all agents see same synthesis
  228. from npcpy.npc_array import NPCArray
  229. def synthesis_round(all_responses):
  230. return f"""Given these perspectives:
  231. {chr(10).join([f'- {r[:200]}...' for r in all_responses])}
  232. Re-solve the problem incorporating insights from all approaches."""
  233. # Chain runs the synthesis function on all responses, then feeds result back
  234. refined = team.infer(f"Solve: {problem}").chain(
  235. synthesis_round,
  236. n_rounds=3
  237. ).collect()
  238. ```
  239. ### Knowledge Graph with Sleep/Dream Lifecycle
  240. ```python
  241. from npcpy.memory.knowledge_graph import (
  242. kg_initial, kg_evolve_incremental, kg_sleep_process, kg_dream_process
  243. )
  244. from npcpy.llm_funcs import get_llm_response
  245. # Initialize KG from text corpus
  246. content_text = """Pirate Prentice is in the lavatory stands pissing. Then he threads himself into a wool robe he wears inside out.
  247. The day feels like rain."""
  248. kg = kg_initial(content_text, model="gemma3:4b", provider="ollama")
  249. # Evolve with new content
  250. new_content = """The phone call, when it comes, rips easily across the room.
  251. Pirate knows it's got to be for him."""
  252. kg, _ = kg_evolve_incremental(kg, new_content, model="gemma3:4b", provider="ollama")
  253. # Sleep - consolidate and prune
  254. kg, sleep_report = kg_sleep_process(kg, model="gemma3:4b", provider="ollama")
  255. # Dream - generate speculative connections
  256. kg, dream_report = kg_dream_process(kg, model="gemma3:4b", provider="ollama", num_seeds=3)
  257. print(f"KG has {len(kg['facts'])} facts and {len(kg['concepts'])} concepts")
  258. assert len(kg['facts']) > 0, "KG extraction returned no facts"
  259. assert len(kg['concepts']) > 0, "KG extraction returned no concepts"
  260. ```
  261. ### Flask Serving for NPC Teams
  262. ```python
  263. from npcpy.serve import start_flask_server
  264. import os
  265. # Serve your NPC team via REST API
  266. if __name__ == "__main__":
  267. is_dev = not getattr(os.sys, 'frozen', False)
  268. port = os.environ.get('INCOGNIDE_PORT', '5437' if is_dev else '5337')
  269. frontend_port = os.environ.get('FRONTEND_PORT', '7337' if port == '5437' else '6337')
  270. start_flask_server(
  271. port=port,
  272. cors_origins=f"localhost:{frontend_port}",
  273. db_path=os.path.expanduser('~/npcsh_history.db'),
  274. user_npc_directory=os.path.expanduser('~/.npcsh/npc_team'),
  275. debug=False
  276. )
  277. ```
  278. ### Streaming
  279. ```python
  280. from npcpy import get_llm_response
  281. from npcpy.streaming import parse_stream_chunk
  282. response = get_llm_response("Explain quantum entanglement.", model='qwen3.5:2b', provider='ollama', stream=True)
  283. for chunk in response['response']:
  284. content, _, _ = parse_stream_chunk(chunk, provider='ollama')
  285. if content:
  286. print(content, end='', flush=True)
  287. # Works the same with any provider
  288. response = get_llm_response("Explain quantum entanglement.", model='gemini-2.5-flash', provider='gemini', stream=True)
  289. for chunk in response['response']:
  290. content, _, _ = parse_stream_chunk(chunk, provider='gemini')
  291. if content:
  292. print(content, end='', flush=True)
  293. ```
  294. ### JSON output
  295. Include the expected JSON structure in your prompt. With `format='json'`, the response is auto-parsed — `response['response']` is already a dict or list.
  296. ```python
  297. from npcpy import get_llm_response
  298. response = get_llm_response(
  299. '''List 3 planets from the sun.
  300. Return JSON: {"planets": [{"name": "planet name", "distance_au": 0.0, "num_moons": 0}]}''',
  301. model='qwen3.5:2b', provider='ollama',
  302. format='json'
  303. )
  304. for planet in response['response']['planets']:
  305. print(f"{planet['name']}: {planet['distance_au']} AU, {planet['num_moons']} moons")
  306. response = get_llm_response(
  307. '''Analyze this review: 'The battery life is amazing but the screen is too dim.'
  308. Return JSON: {"tone": "positive/negative/mixed", "key_phrases": ["phrase1", "phrase2"], "confidence": 0.0}''',
  309. model='qwen3.5:2b', provider='ollama',
  310. format='json'
  311. )
  312. result = response['response']
  313. print(result['tone'], result['key_phrases'])
  314. ```
  315. <details>
  316. <summary><b>Pydantic structured output</b></summary>
  317. Pass a Pydantic model and the JSON schema is sent to the LLM directly.
  318. ```python
  319. from npcpy import get_llm_response
  320. from pydantic import BaseModel
  321. from typing import List
  322. class Planet(BaseModel):
  323. name: str
  324. distance_au: float
  325. num_moons: int
  326. class SolarSystem(BaseModel):
  327. planets: List[Planet]
  328. response = get_llm_response(
  329. "List the first 4 planets from the sun.",
  330. model='qwen3.5:2b', provider='ollama',
  331. format=SolarSystem
  332. )
  333. for p in response['response']['planets']:
  334. print(f"{p['name']}: {p['distance_au']} AU, {p['num_moons']} moons")
  335. ```
  336. </details>
  337. <details>
  338. <summary><b>Image, audio, and video generation</b></summary>
  339. ```python
  340. from npcpy.llm_funcs import gen_image, gen_video
  341. from npcpy.gen.audio_gen import text_to_speech
  342. # Image — OpenAI, Gemini, Ollama, or diffusers
  343. images = gen_image("A sunset over the mountains", model='gemma3:4b', provider='ollama')
  344. images[0].save("sunset.png")
  345. # Audio — OpenAI, Gemini, ElevenLabs, Kokoro, gTTS
  346. audio_bytes = text_to_speech("Hello from npcpy!", engine="gtts")
  347. with open("hello.wav", "wb") as f:
  348. f.write(audio_bytes)
  349. # Video — Gemini Veo
  350. result = gen_video("A cat riding a skateboard", model='veo-3.1-fast-generate-preview', provider='gemini')
  351. print(result['output'])
  352. ```
  353. </details>
  354. ### Multi-agent team
  355. ```python
  356. from npcpy import NPC, Team
  357. team = Team(team_path='examples/npc_team')
  358. result = team.orchestrate("Analyze the latest sales data and draft a report")
  359. print(result['output'])
  360. ```
  361. Or define a team in code:
  362. ```python
  363. from npcpy import NPC, Team
  364. coordinator = NPC(name='lead', primary_directive='Coordinate the team. Delegate to @analyst and @writer.')
  365. analyst = NPC(name='analyst', primary_directive='Analyze data. Provide numbers and trends.', model='gemini-2.5-flash', provider='gemini')
  366. writer = NPC(name='writer', primary_directive='Write clear reports from analysis.', model='qwen3:8b', provider='ollama')
  367. team = Team(npcs=[coordinator, analyst, writer], forenpc='lead')
  368. result = team.orchestrate("What are the trends in renewable energy adoption?")
  369. print(result['output'])
  370. ```
  371. <details>
  372. <summary><b>Team from files — .npc, .jinx, team.ctx</b></summary>
  373. **team.ctx:**
  374. ```yaml
  375. context: |
  376. Research team for analyzing scientific literature.
  377. The lead delegates to specialists as needed.
  378. forenpc: lead
  379. model: qwen3.5:2b
  380. provider: ollama
  381. output_format: markdown
  382. max_search_results: 5
  383. mcp_servers:
  384. - path: ~/.npcsh/mcp_server.py
  385. ```
  386. **lead.npc:**
  387. ```yaml
  388. #!/usr/bin/env npc
  389. name: lead
  390. primary_directive: |
  391. You lead the research team. Delegate literature searches to @searcher,
  392. data analysis to @analyst. Synthesize their findings into a coherent summary.
  393. jinxes:
  394. - {{ Jinx('sh') }}
  395. - {{ Jinx('python') }}
  396. - {{ Jinx('delegate') }}
  397. - {{ Jinx('web_search') }}
  398. ```
  399. **searcher.npc:**
  400. ```yaml
  401. #!/usr/bin/env npc
  402. name: searcher
  403. primary_directive: |
  404. You search for scientific papers and extract key findings.
  405. Use web_search and load_file to find and read papers.
  406. model: gemini-2.5-flash
  407. provider: gemini
  408. jinxes:
  409. - {{ Jinx('web_search') }}
  410. - {{ Jinx('load_file') }}
  411. - {{ Jinx('sh') }}
  412. ```
  413. **Jinxes can reference a specific NPC** to always run under that persona, and **access `ctx` variables** from `team.ctx`:
  414. **jinxes/search_and_summarize.jinx:**
  415. ```yaml
  416. #!/usr/bin/env npc
  417. jinx_name: search_and_summarize
  418. description: Search for papers and summarize findings using the searcher NPC.
  419. npc: {{ NPC('searcher') }}
  420. inputs:
  421. - query
  422. steps:
  423. - name: search
  424. engine: natural
  425. code: |
  426. Search for papers about {{ query }}.
  427. Return up to {{ ctx.max_search_results }} results.
  428. - name: summarize
  429. engine: natural
  430. code: |
  431. Summarize the findings in {{ ctx.output_format }} format:
  432. {{ output }}
  433. ```
  434. The `npc:` field binds the jinx to a specific NPC — when this jinx runs, it always uses the `searcher` persona regardless of which NPC invoked it. Any custom keys in `team.ctx` (like `output_format`, `max_search_results`) are available as `{{ ctx.key }}` in Jinja templates and as `context['key']` in Python steps.
  435. ```
  436. my_project/
  437. ├── npc_team/
  438. │ ├── team.ctx
  439. │ ├── lead.npc
  440. │ ├── searcher.npc
  441. │ ├── analyst.npc
  442. │ ├── jinxes/
  443. │ │ └── skills/
  444. │ └── models/
  445. ├── agents.md # Optional: define agents in markdown
  446. └── agents/ # Optional: one .md file per agent
  447. └── translator.md
  448. ```
  449. `.npc` and `.jinx` files are directly executable:
  450. ```bash
  451. ./npc_team/lead.npc "summarize the latest arxiv papers on transformers"
  452. ./npc_team/jinxes/lib/sh.jinx bash_command="echo hello"
  453. ```
  454. </details>
  455. <details>
  456. <summary><b>MCP server integration</b></summary>
  457. Add MCP servers to your team for external tool access:
  458. **team.ctx:**
  459. ```yaml
  460. forenpc: assistant
  461. mcp_servers:
  462. - path: ./tools/db_server.py
  463. - path: ./tools/api_server.py
  464. ```
  465. **db_server.py:**
  466. ```python
  467. from mcp.server.fastmcp import FastMCP
  468. mcp = FastMCP("Database Tools")
  469. @mcp.tool()
  470. def query_orders(customer_id: str, limit: int = 10) -> str:
  471. """Query recent orders for a customer."""
  472. # Your database logic here
  473. return f"Found {limit} orders for customer {customer_id}"
  474. @mcp.tool()
  475. def search_products(query: str) -> str:
  476. """Search the product catalog."""
  477. return f"Products matching: {query}"
  478. if __name__ == "__main__":
  479. mcp.run()
  480. ```
  481. The team's NPCs automatically get access to MCP tools alongside their jinxes.
  482. For a remote server that uses Streamable HTTP, set its transport explicitly.
  483. For example, Parallel Search MCP provides live web search and URL fetching
  484. without requiring an account or API key:
  485. ```yaml
  486. forenpc: assistant
  487. mcp_servers:
  488. - url: https://search.parallel.ai/mcp
  489. transport: streamable-http
  490. headers:
  491. User-Agent: npcpy
  492. tools:
  493. - web_search
  494. - web_fetch
  495. ```
  496. [Cohesivity](https://cohesivity.ai?ref=gh-npcpy) MCP gives NPCs an on-the-fly
  497. backend (hosting, Postgres, storage, auth, email, AI APIs) without requiring an
  498. account or API key:
  499. ```yaml
  500. forenpc: assistant
  501. mcp_servers:
  502. - url: https://cohesivity.ai/mcp
  503. transport: streamable-http
  504. headers:
  505. User-Agent: npcpy
  506. tools:
  507. - create_tenant
  508. - claim_tenant
  509. - tenant_status
  510. - provision_resource
  511. - give_feedback
  512. - get_cohesivity_documentation
  513. ```
  514. [deed.page](https://deed.page/docs) MCP lets an NPC publish the HTML or files it
  515. produces to a public `https://{slug}.deed.page/` URL without an account or API
  516. key. The first `publish_site` call returns an owner token; pass it as `token`
  517. to later `update_site` and `delete_site` calls. Published pages are public:
  518. ```yaml
  519. forenpc: assistant
  520. mcp_servers:
  521. - url: https://deed.page/mcp
  522. transport: streamable-http
  523. headers:
  524. User-Agent: npcpy
  525. tools:
  526. - publish_site
  527. - update_site
  528. - get_site
  529. - delete_site
  530. ```
  531. Remote URLs continue to use SSE when `transport` is omitted.
  532. </details>
  533. <details>
  534. <summary><b>Agent definitions in markdown &amp; Skills</b></summary>
  535. **agents.md** — multiple agents in one file:
  536. ```markdown
  537. ## summarizer
  538. You summarize long documents into concise bullet points.
  539. Focus on key findings, methodology, and conclusions.
  540. ## fact_checker
  541. You verify claims against reliable sources and flag inaccuracies.
  542. Always cite your sources.
  543. ```
  544. **agents/translator.md** — one file per agent with optional frontmatter:
  545. ```markdown
  546. ---
  547. model: gemini-2.5-flash
  548. provider: gemini
  549. ---
  550. You translate content between languages while preserving tone and idiom.
  551. ```
  552. Skills are knowledge-content jinxes that provide instructional sections to agents on demand.
  553. **npc_team/jinxes/skills/code-review/SKILL.md:**
  554. ```markdown
  555. ---
  556. name: code-review
  557. description: Use when reviewing code for quality, security, and best practices.
  558. ---
  559. # Code Review Skill
  560. ## checklist
  561. - Check for security vulnerabilities (SQL injection, XSS, etc.)
  562. - Verify error handling and edge cases
  563. - Review naming conventions and code clarity
  564. ## security
  565. Focus on OWASP top 10 vulnerabilities...
  566. ```
  567. Reference in your NPC:
  568. ```yaml
  569. jinxes:
  570. - {{ Jinx('skills/code-review') }}
  571. ```
  572. </details>
  573. ### NPCArray — parallel jinx across multiple NPCs
  574. Run any jinx in parallel across a list of NPC instances and collect results as an array:
  575. ```python
  576. from npcpy import NPC
  577. from npcpy.npc_array import NPCArray
  578. # Three NPCs with different models/providers
  579. npcs = [
  580. NPC(name='gramsci_1930', primary_directive='''
  581. You are Antonio Gramsci writing in his Prison Notebook in 1930.
  582. Defend the concept of hegemony as the predominance of one social group
  583. over others through cultural and ideological leadership rather than
  584. mere force. Argue that consent is more durable than coercion.
  585. ''', model='qwen3:4b', provider='ollama'),
  586. NPC(name='critic_1970', primary_directive='''
  587. You are a post-structuralist critic in 1970 responding to Gramsci.
  588. Question whether hegemony can truly explain contemporary power structures
  589. or if it relies on an outdated base-superstructure model that
  590. underestimates the autonomy of cultural production.
  591. ''', model='qwen3:4b', provider='ollama'),
  592. NPC(name='historian_present', primary_directive='''
  593. You are a contemporary historian with access to the complete Prison
  594. Notebooks and subsequent scholarship. Evaluate both Gramsci's original
  595. formulation and the post-structuralist critique in light of the
  596. collapse of actually existing socialism and the rise of neoliberalism.
  597. ''', model='qwen3:4b', provider='ollama'),
  598. ]
  599. arr = NPCArray.from_npcs(npcs)
  600. # Run the same jinx on all three in parallel, collect results
  601. results = arr.jinx('analyze', inputs={'topic': 'Has the concept of hegemony become more or less relevant in the age of digital platforms and algorithmic governance?'}).collect()
  602. for npc, result in zip(npcs, results.data):
  603. print(f"[{npc.name}] {result}")
  604. ```
  605. You can also pass a list directly to `jinx.execute()`:
  606. ```python
  607. from npcpy.npc_compiler import Jinx
  608. jinx = Jinx(jinx_path='examples/npc_team/jinxes/analyze.jinx')
  609. results = jinx.execute({'topic': 'rate limiting'}, npc=npcs) # list → parallel NPCArray run
  610. ```
  611. <details>
  612. <summary><b>Knowledge graphs</b></summary>
  613. Build, evolve, and search knowledge graphs from text. The KG grows through waking (assimilation), sleeping (consolidation), and dreaming (speculative synthesis).
  614. ```python
  615. from npcpy.memory.knowledge_graph import (
  616. kg_initial, kg_evolve_incremental, kg_sleep_process,
  617. kg_dream_process, kg_hybrid_search,
  618. )
  619. # Seed the KG with Gramsci's Prison Notebooks
  620. kg = kg_initial(
  621. content="""
  622. The crisis consists precisely in the fact that the old is dying and the new
  623. cannot be born. In this interregnum a great variety of morbid symptoms appear.
  624. The traditional ruling class has lost its consensus, that is, the consent of
  625. those over whom it rules. Force alone is not sufficient; what is needed is the
  626. construction of a new hegemony, the creation of a new collective will.
  627. """,
  628. model="qwen3:4b", provider="ollama",
  629. )
  630. # Assimilate more content on organic vs traditional intellectuals
  631. kg, _ = kg_evolve_incremental(
  632. kg,
  633. new_content_text="""
  634. The distinction between organic and traditional intellectuals is fundamental.
  635. Traditional intellectuals conceive of themselves as autonomous from ruling
  636. groups, yet every social group has its own category of organic intellectuals
  637. that give it homogeneity and awareness of its own function. The organic
  638. intellectual emerges from within the class itself, while the traditional
  639. sees himself as existing above the social structure.
  640. """,
  641. model="qwen3:4b", provider="ollama", get_concepts=True,
  642. )
  643. # Consolidate — merge redundant nodes, strengthen high-frequency edges
  644. kg, sleep_report = kg_sleep_process(kg, model="qwen3:4b", provider="ollama")
  645. # Dream — generate speculative connections between loosely related concepts
  646. kg, dream_report = kg_dream_process(kg, model="qwen3:4b", provider="ollama")
  647. # Search across facts, concepts, and speculative edges
  648. results = kg_hybrid_search(kg, "What constitutes hegemony in Gramsci's framework?",
  649. model="qwen3:4b", provider="ollama")
  650. for r in results:
  651. print(r['score'], r['text'])
  652. print(f"{len(kg['facts'])} facts, {len(kg['concepts'])} concepts")
  653. ```
  654. Extract structured memories:
  655. ```python
  656. from npcpy.llm_funcs import get_facts
  657. prison_notebooks = """
  658. Civil society is the sphere of hegemony, the terrain where the dominant
  659. group exercises consent through cultural and ideological leadership.
  660. Unlike political society which operates through coercion and state apparatus,
  661. civil society comprises the church, schools, trade unions, and media.
  662. The ruling class maintains power not merely through force but through the
  663. production of consent, shaping common sense itself through cultural institutions.
  664. War of position requires patient trench warfare on this terrain, building
  665. counter-hegemonic institutions rather than frontal assault on the state.
  666. """
  667. facts = get_facts(prison_notebooks, model="qwen3:4b", provider="ollama")
  668. for f in facts:
  669. print(f"[{f.get('type', 'general')}] {f['statement']}")
  670. ```
  671. </details>
  672. <details>
  673. <summary><b>Sememolution — population-based KG evolution</b></summary>
  674. Maintain a population of KG variants that evolve independently. Each individual has Poisson-sampled search parameters, producing different traversals each query. Selection pressure from response ranking drives convergence toward useful graph structures.
  675. ```python
  676. from npcpy.memory.kg_population import SememolutionPopulation
  677. pop = SememolutionPopulation(model='qwen3.5:2b', provider='ollama', population_size=100, sample_size=10)
  678. pop.initialize()
  679. pop.assimilate_text("""
  680. The debate over lunar resource extraction has intensified since the discovery
  681. of water ice in permanently shadowed regions at the lunar poles. While some
  682. researchers argue that commercial mining could fund further exploration,
  683. others warn that unregulated extraction could contaminate scientifically
  684. valuable sites that have remained pristine for billions of years. The
  685. Artemis Accords attempt to establish a framework for international
  686. cooperation, but major spacefaring nations have yet to reach consensus
  687. on property rights and environmental protection standards.
  688. """)
  689. pop.assimilate_text("""
  690. Tidal acceleration gradually increases the orbital distance between Earth
  691. and Moon at a rate of approximately 3.8 centimeters per year. This
  692. phenomenon results from angular momentum transfer via gravitational
  693. interaction, simultaneously slowing Earth's rotation and lengthening the
  694. day. Paleontological evidence from tidal rhythmites suggests that 620
  695. million years ago, a day lasted only 21.9 hours and the lunar month was
  696. just 27.5 days. Projections indicate that in approximately 600 million
  697. years, tidal effects will no longer support total solar eclipses.
  698. """)
  699. # Sleep/dream cycle — each individual consolidates according to its genome
  700. pop.sleep_cycle()
  701. # Query: sample 10 individuals, generate competing responses, rank them
  702. rankings = pop.query_and_rank("What are the central themes connecting these documents?")
  703. for rank, entry in enumerate(rankings[:3], 1):
  704. print(f"#{rank} (individual {entry['id']}, score {entry['score']:.3f}): {entry['response'][:120]}...")
  705. # Selection + reproduction — top performers breed, bottom are replaced
  706. pop.evolve_generation()
  707. stats = pop.get_stats()
  708. print(f"Generation {stats['generation']} | avg fitness {stats['avg_fitness']:.3f} | "
  709. f"best fitness {stats['best_fitness']:.3f} | diversity {stats['diversity']:.3f}")
  710. ```
  711. </details>
  712. <details>
  713. <summary><b>Fine-tuning (SFT, RL, MLX)</b></summary>
  714. **RL Training with DPO for Tool-Calling Agents**
  715. ```python
  716. from npcpy.npc_compiler import NPC
  717. from npcpy.ft.rl import RLConfig, train_with_dpo, load_rl_model
  718. import json
  719. def npcsh_reward(trace):
  720. """Reward function for shell assistant responses."""
  721. output = trace.get('final_output', '')
  722. completed = trace.get('completed', False)
  723. score = 0.0
  724. if completed:
  725. score += 2.0
  726. if 50 < len(output) < 1500:
  727. score += 1.0
  728. if '```' in output:
  729. score += 1.0
  730. if any(cmd in output.lower() for cmd in ['ls', 'cd', 'cat', 'grep', 'find', 'pip', 'git']):
  731. score += 0.3
  732. return max(0.0, min(10.0, score + 5.0))
  733. # Load preference pairs from agent traces
  734. traces = []
  735. with open('preference_pairs.jsonl', 'r') as f:
  736. for line in f:
  737. pair = json.loads(line)
  738. traces.append({
  739. 'task_prompt': pair['prompt'],
  740. 'final_output': pair['chosen'],
  741. 'reward': pair.get('chosen_score', 8.0),
  742. 'completed': True
  743. })
  744. traces.append({
  745. 'task_prompt': pair['prompt'],
  746. 'final_output': pair['rejected'],
  747. 'reward': pair.get('rejected_score', 3.0),
  748. 'completed': False
  749. })
  750. config = RLConfig(
  751. base_model_name="Qwen/Qwen2.5-0.5B-Instruct",
  752. adapter_path="./npcsh_adapter",
  753. num_train_epochs=3,
  754. per_device_train_batch_size=2,
  755. learning_rate=5e-5,
  756. beta=0.1
  757. )
  758. adapter_path = train_with_dpo(traces, config)
  759. print(f"Trained adapter saved to: {adapter_path}")
  760. ```
  761. **SFT for Scientific Writing Style Transfer**
  762. ```python
  763. from npcpy.llm_funcs import get_llm_response
  764. from npcpy.ft import SFTConfig, run_sft
  765. # Generate scientific writing dataset from style samples
  766. def generate_scientific_trace(question, reasoning_model, converter_model, style_chunks):
  767. """Generate native reasoning then rewrite in scientific voice."""
  768. # Step 1: Get reasoning trace
  769. native_prompt = f"""Answer this question with detailed reasoning.
  770. Question: {question}
  771. Provide your step-by-step reasoning and final answer."""
  772. native_response = get_llm_response(native_prompt, model=reasoning_model, provider='ollama')
  773. native_trace = native_response['response']
  774. # Step 2: Rewrite in scientific style
  775. style_context = '\n\n---\n\n'.join(style_chunks[:8])
  776. rewrite_prompt = f"""Rewrite the following reasoning trace in the scientific writing style demonstrated by the excerpts below.
  777. Original Reasoning Trace:
  778. {native_trace}
  779. SCIENTIFIC PAPER EXCERPTS:
  780. {style_context}
  781. Task:
  782. 1. Rewrite the reasoning in the style of the scientific paper excerpts
  783. 2. Use LaTeX notation where appropriate
  784. 3. Preserve the logical flow and factual content
  785. 4. Match the prose density and intellectual register"""
  786. rewritten = get_llm_response(rewrite_prompt, model=converter_model, provider='ollama')
  787. return rewritten['response']
  788. # Train on generated examples
  789. X_train = ["What is the relationship between quantum contextuality and natural language interpretation?"]
  790. y_train = [generate_scientific_trace(X_train[0], 'qwen3:8b', 'qwen3:8b', style_chunks)]
  791. sft_config = SFTConfig(
  792. base_model_name="Qwen/Qwen3-4B",
  793. output_model_path="models/scientific-writer",
  794. device='mlx',
  795. num_train_epochs=100,
  796. per_device_train_batch_size=1,
  797. lora_r=128,
  798. lora_alpha=256
  799. )
  800. model_path = run_sft(X_train, y_train, config=sft_config, format_style="llama")
  801. ```
  802. </details>
  803. ## Features
  804. - **[Agents (NPCs)](https://npcpy.readthedocs.io/en/latest/guides/agents/)** — Agents with personas, directives, and tool calling. Subclasses: `Agent` (default tools), `ToolAgent` (custom tools + MCP), `CodingAgent` (auto-execute code blocks)
  805. - **[Multi-Agent Teams](https://npcpy.readthedocs.io/en/latest/guides/teams/)** — Team orchestration with a coordinator (forenpc)
  806. - **[Jinx Workflows](https://npcpy.readthedocs.io/en/latest/guides/jinx-workflows/)** — Jinja Execution templates for multi-step prompt pipelines
  807. - **[Skills](https://npcpy.readthedocs.io/en/latest/guides/skills/)** — Knowledge-content jinxes that serve instructional sections to agents on demand
  808. - **[NPCArray](https://npcpy.readthedocs.io/en/latest/guides/npc-array/)** — NumPy-like vectorized operations over model populations
  809. - **[Image, Audio & Video](https://npcpy.readthedocs.io/en/latest/guides/image-audio-video/)** — Generation via Ollama, diffusers, OpenAI, Gemini, ElevenLabs
  810. - **[Knowledge Graphs](https://npcpy.readthedocs.io/en/latest/guides/knowledge-graphs/)** — Build and evolve knowledge graphs from text with sleep/dream lifecycle
  811. - **[Sememolution](https://npcpy.readthedocs.io/en/latest/guides/knowledge-graphs/#sememolution-population-based-kg-evolution)** — Population-based KG evolution with genetic selection and Poisson-sampled search
  812. - **[Memory Pipeline](https://npcpy.readthedocs.io/en/latest/guides/knowledge-graphs/#memory-extraction-and-lifecycle)** — Extract, approve, and backfill memories with self-improving quality feedback
  813. - **[Fine-Tuning & Evolution](https://npcpy.readthedocs.io/en/latest/guides/fine-tuning/)** — SFT, USFT, RL/DPO, diffusion, genetic algorithms, MLX on Apple Silicon
  814. - **[Serving](https://npcpy.readthedocs.io/en/latest/guides/serving/)** — Flask server for deploying teams via REST API
  815. - **[ML Functions](https://npcpy.readthedocs.io/en/latest/guides/ml-funcs/)** — Scikit-learn grid search, ensemble prediction, PyTorch training
  816. - **[Streaming & JSON](https://npcpy.readthedocs.io/en/latest/guides/llm-responses/)** — Streaming responses, structured JSON output, message history
  817. ## Providers
  818. Works with all major LLM providers through LiteLLM: `airllm`, `anthropic`, `deepseek`, `gemini`, `ollama`, `openai`, `openai-like`, and more.
  819. <details><summary>API Route</summary>
  820. Set `API_ROUTE_API_KEY` and use `provider="api-route"` with an exact model ID from your account's authenticated `GET /v1/models` response, for example `gpt-6.1-sol`. [API Route](https://api-route.com) uses the OpenAI-compatible Base URL `https://global.api-route.com/v1`; set `API_ROUTE_API_URL` to override it. The alias `api_route` is also accepted. Explicit `api_url` and `api_key` arguments take precedence.
  821. ```python
  822. from npcpy import get_llm_response
  823. response = get_llm_response("Say hello in one short sentence.", model="gpt-6.1-sol", provider="api-route")
  824. print(response["response"])
  825. ```
  826. </details>
  827. <details><summary>Atlas Cloud</summary>
  828. Set `ATLASCLOUD_API_KEY` and use `provider="atlascloud"` with any model ID from the [Atlas Cloud model list](https://www.atlascloud.ai/models), for example `deepseek-ai/deepseek-v4-flash`, `zai-org/glm-5.2` or `moonshotai/kimi-k3`. Requests go to the OpenAI-compatible Base URL `https://api.atlascloud.ai/v1`; set `ATLASCLOUD_API_URL` to override it.
  829. ```python
  830. response = get_llm_response("Say hello in one short sentence.", model="deepseek-ai/deepseek-v4-flash", provider="atlascloud")
  831. print(response["response"])
  832. ```
  833. </details>
  834. <details><summary>cheapaimodel</summary>
  835. Set `CHEAPAIMODEL_API_KEY` and use `provider="cheapaimodel"` with a model ID from the [model list](https://cheapaimodel.ai/models), for example `deepseek-v4-1-flash`, `glm-5.3`, `kimi-k3` or `grok-4.7`. Requests go to the OpenAI-compatible base URL `https://api.cheapaimodel.ai/v1`; set `CHEAPAIMODEL_API_URL` to override it. Usage is billed per token from a prepaid USD balance; create a key in the [console](https://console.cheapaimodel.ai/keys). See the [docs](https://cheapaimodel.ai/docs) or [cheapaimodel.ai](https://cheapaimodel.ai/?utm_source=npcpy).
  836. ```python
  837. response = get_llm_response("Say hello in one short sentence.", model="deepseek-v4-1-flash", provider="cheapaimodel")
  838. print(response["response"])
  839. ```
  840. </details>
  841. <details><summary>Cheaper Inference</summary>
  842. Set `CHEAPER_INFERENCE_API_KEY` and use `provider="cheaperinference"` with any model ID from the [Cheaper Inference model list](https://cheaperinference.com/markets), for example `gpt-5.4-mini`, `claude-sonnet-5` or `glm-5.3`. Requests go to the OpenAI-compatible Base URL `https://api.cheaperinference.com/v1`; set `CHEAPER_INFERENCE_API_URL` to override it.
  843. ```python
  844. response = get_llm_response("Say hello in one short sentence.", model="gpt-5.4-mini", provider="cheaperinference")
  845. print(response["response"])
  846. ```
  847. </details>
  848. <details><summary>CloudGPU</summary>
  849. Set `CLOUDGPU_API_KEY` and use `provider="cloudgpu"` with a model ID from CloudGPU's model list (`GET https://cloudgpu.app/v1/models`), for example `deepseek-v4.1-flash`, `kimi-k2.7-code` or `glm-5.3-flash`. Requests go to the OpenAI-compatible base URL `https://cloudgpu.app/v1`; set `CLOUDGPU_API_URL` to override it. Keys are created in the CloudGPU console; see the [API docs](https://cloudgpu.app/api/docs?utm_source=github&utm_medium=referral&utm_campaign=202611_seg06_indiedev&utm_content=github_npcpy_provider).
  850. ```python
  851. response = get_llm_response("Say hello in one short sentence.", model="deepseek-v4.1-flash", provider="cloudgpu")
  852. print(response["response"])
  853. ```
  854. </details>
  855. <details><summary>MiniMax</summary>
  856. Set `MINIMAX_API_KEY` and use `provider="minimax"`. When no model is configured, `MiniMax-M3.1-Flash` is the default; the model list offers it first, followed by `MiniMax-M3`. Explicit saved or custom model IDs remain supported, including legacy IDs. The optional `MINIMAX_API_URL` setting selects the region and compatible protocol; it defaults to the global OpenAI-compatible Base URL.
  857. | Region | OpenAI-compatible Base URL | Anthropic-compatible Base URL |
  858. | --- | --- | --- |
  859. | Global | `https://api.minimax.io/v1` | `https://api.minimax.io/anthropic` |
  860. | China | `https://api.minimaxi.com/v1` | `https://api.minimaxi.com/anthropic` |
  861. Use the Anthropic-compatible Base URL exactly as shown. The client appends `/v1/messages` when sending a request.
  862. For Flash, use adaptive thinking (`thinking={"type": "adaptive"}`) and an optional `reasoning_effort` of `low`, `medium`, `high`, `xhigh`, or `max`; Anthropic-compatible requests send this as `output_config.effort`. Flash does not support disabled thinking. M3 retains its existing thinking modes. OpenRouter lists `minimax/minimax-m3.1-flash:free` first and `minimax/minimax-m3` second, using their full gateway IDs.
  863. </details>
  864. <details><summary>Obscurify.ai</summary>
  865. Set `OBSCURIFY_API_KEY` and use `provider="obscurify"` with a model ID from the public model list (`GET https://obscurify.ai/v1/models`, no key needed), for example `deepseek/deepseek-v4-flash`, `moonshotai/kimi-k2-0905` or `z-ai/glm-5.3`. Requests go to the OpenAI-compatible base URL `https://obscurify.ai/v1`; set `OBSCURIFY_API_URL` to override it. Accounts are a random account number with no email; the key is under "Show API Key" on the [account page](https://obscurify.ai/account). See the [API docs](https://obscurify.ai/api-docs) or [obscurify.ai](https://obscurify.ai/?utm_source=npcpy).
  866. ```python
  867. response = get_llm_response("Say hello in one short sentence.", model="deepseek/deepseek-v4-flash", provider="obscurify")
  868. print(response["response"])
  869. ```
  870. </details>
  871. <details><summary>Opper</summary>
  872. Set `OPPER_API_KEY` and use `provider="opper"` with any model ID from the [Opper model catalogue](https://opper.ai/models), for example `claude-sonnet-4-6`, `gpt-5.4-mini` or `gemini-3.8-flash`. These pool names route across the providers serving that model; a `provider/model` ID such as `anthropic/claude-sonnet-4-6` pins one route. Requests go to the OpenAI-compatible Base URL `https://api.opper.ai/v3/compat`; set `OPPER_API_URL` to override it. Keys are created at [platform.opper.ai](https://platform.opper.ai).
  873. ```python
  874. response = get_llm_response("Say hello in one short sentence.", model="claude-sonnet-4-6", provider="opper")
  875. print(response["response"])
  876. ```
  877. </details>
  878. <details><summary>Requesty</summary>
  879. Set `REQUESTY_API_KEY` and use `provider="requesty"` with a `vendor/model` ID from Requesty's public model list (`GET https://router.requesty.ai/v1/models`), for example `openai/gpt-4o-mini`, `anthropic/claude-sonnet-5` or `google/gemini-2.5-flash`. Requests go to the OpenAI-compatible Base URL `https://router.requesty.ai/v1` and are routed to the first-party providers (OpenAI, Anthropic, Google and others); set `REQUESTY_API_URL` to override it, for example `https://router.eu.requesty.ai/v1` for the EU endpoint. Keys are created in the [Requesty dashboard](https://app.requesty.ai/api-keys).
  880. ```python
  881. response = get_llm_response("Say hello in one short sentence.", model="openai/gpt-4o-mini", provider="requesty")
  882. print(response["response"])
  883. ```
  884. </details>
  885. <details><summary>Runcrate</summary>
  886. Set `RUNCRATE_API_KEY` and use `provider="runcrate"` with any `vendor/model` ID from Runcrate's public model list (`GET https://api.runcrate.ai/v1/models`), for example `deepseek-ai/DeepSeek-V4.1-Flash` or `openai/gpt-oss-120b`. Requests go to the OpenAI-compatible Base URL `https://api.runcrate.ai/v1`; set `RUNCRATE_API_URL` to override it. Open models are free with your GitHub account; keys are created in the [Runcrate dashboard](https://www.runcrate.ai/dashboard/api-keys?utm_source=npcpy&utm_medium=directory&utm_campaign=gpu_pricing).
  887. ```python
  888. response = get_llm_response("Say hello in one short sentence.", model="deepseek-ai/DeepSeek-V4.1-Flash", provider="runcrate")
  889. print(response["response"])
  890. ```
  891. </details>
  892. <details><summary>UberLLM</summary>
  893. Set `UBERLLM_API_KEY` and use `provider="uberllm"` with a `vendor/model` ID from UberLLM's public model list (`GET https://api.uberllm.dev/v1/models`), for example `deepseek/deepseek-v4.1-flash`, `openai/gpt-5.4-mini` or `anthropic/claude-sonnet-4.6`. Requests go to the OpenAI-compatible base URL `https://api.uberllm.dev/v1`; set `UBERLLM_API_URL` to override it. Usage is prepaid and billed per request (failed requests are not billed); per-model prices are on the [model list](https://uberllm.dev/models) and keys are created at [uberllm.dev/signup](https://uberllm.dev/signup). See the [quickstart](https://uberllm.dev/docs/quickstart).
  894. ```python
  895. response = get_llm_response("Say hello in one short sentence.", model="deepseek/deepseek-v4.1-flash", provider="uberllm")
  896. <details><summary>Standard Compute</summary>
  897. Set `STANDARDCOMPUTE_API_KEY` and use `provider="standardcompute"`. The model `StandardCompute` is routed: each request goes to the cheapest enabled model that can handle it, with automatic fallback. To pin a model, use any ID from the public model list (`GET https://api.stdcmpt.com/v1/models`), for example `deepseek/deepseek-v4.1-flash` or `z-ai/glm-5.3`. Requests go to the OpenAI-compatible Base URL `https://api.stdcmpt.com/v1`; set `STANDARDCOMPUTE_API_URL` to override it. Keys are created at [standardcompute.com](https://standardcompute.com/?utm_source=npcpy).
  898. ```python
  899. response = get_llm_response("Say hello in one short sentence.", model="StandardCompute", provider="standardcompute")
  900. print(response["response"])
  901. ```
  902. </details>
  903. ## QLLM-PAM (local, attention-free)
  904. `npcpy` can run the QLLM-PAM family of local checkpoints directly. QLLM-PAM is a complex-valued, attention-free language model based on Phase-Associative Memory (PAM); see the [Hugging Face model repo](https://huggingface.co/gowravvishwakarma/qllm-pam-v11-e3k3-chat) and the paper on arXiv ([2604.05030](https://arxiv.org/abs/2604.05030)).
  905. ```python
  906. from npcpy import get_llm_response
  907. response = get_llm_response(
  908. "What is the capital of France?",
  909. model="gowravvishwakarma/qllm-pam-v11-e3k3-chat",
  910. provider="qllm",
  911. max_tokens=32,
  912. temperature=0.0,
  913. )
  914. print(response["response"])
  915. ```
  916. The `model` value can be a Hugging Face repo id (downloaded and cached automatically), a local directory, or a `.pt` file path. Supported kwargs include `max_tokens`, `temperature`, `top_k`, `top_p`, `repetition_penalty`, `stream=True`, and `format="json"`.
  917. ## Installation
  918. ```bash
  919. pip install npcpy # base
  920. pip install npcpy[lite] # + API provider libraries
  921. pip install npcpy[local] # + ollama, diffusers, transformers, airllm
  922. pip install npcpy[tts] # + TTS/STT
  923. pip install npcpy[all] # everything
  924. ```
  925. <details><summary>System dependencies</summary>
  926. **Linux:**
  927. ```bash
  928. sudo apt-get install espeak portaudio19-dev python3-pyaudio ffmpeg libcairo2-dev libgirepository1.0-dev
  929. curl -fsSL https://ollama.com/install.sh | sh
  930. ollama pull qwen3.5:2b
  931. ```
  932. **macOS:**
  933. ```bash
  934. brew install portaudio ffmpeg pygobject3 ollama
  935. brew services start ollama
  936. ollama pull qwen3.5:2b
  937. ```
  938. **Windows:** Install [Ollama](https://ollama.com) and [ffmpeg](https://ffmpeg.org), then `ollama pull qwen3.5:2b`.
  939. </details>
  940. API keys go in a `.env` file:
  941. ```bash
  942. export OPENAI_API_KEY="your_key"
  943. export ANTHROPIC_API_KEY="your_key"
  944. export GEMINI_API_KEY="your_key"
  945. ```
  946. ## Read the Docs
  947. Full documentation, guides, and API reference at [npcpy.readthedocs.io](https://npcpy.readthedocs.io/en/latest/).
  948. ## Links
  949. - **[NPC Shell](https://github.com/npc-worldwide/npcsh)** — Command-line shell for interacting with NPCs
  950. - **[Incognide](https://github.com/npc-worldwide/incognide)** — Desktop environment with AI chat, browser, file viewers, code editor, terminal, knowledge graphs, team management, and more ([download](https://enpisi.com/incognide))
  951. - [incognidium](https://github.com/npc-worldwide/incognidium) - a rust-native web browser with an NPC Team focused on developing and testing the incognidium browser against Firefox and Chromium.
  952. -
  953. ### Use the NPC team data layer organization in other languages:
  954. - [npcrs](https://github.com/npc-worldwide/npcsh) - rust port of npcpy
  955. - [nql](https://github.com/npc-worldwide/nql) - SQL-native framework for running agents inside of databases that support LLMs like Google BigQuery, Snowflake, and Databricks.
  956. - [npcts](https://github.com/npc-worldwide/npcts) - typescript library for NPC data layer
  957. - [npcd](https://github.com/npc-worldwide/npcd) - rust port of npcd
  958. -
  959. ## Research
  960. - A Quantum Semantic Framework for natural language processing: [arxiv](https://arxiv.org/abs/2506.10077), accepted at [QNLP 2025](https://qnlp.ai)
  961. - TinyTim: A Family of Language Models for Divergent Generation [arxiv](https://arxiv.org/abs/2508.11607), accepted at NeurIPS 2025 Creative AI Track
  962. - The production of meaning in the processing of natural language: [arxiv](https://arxiv.org/abs/2603.20381), accepted at [QNLP 2026](https://qnlp.ai)
  963. - Herding CATs: ALARA for Agent Harness Engineering in Portable Composable Multi-Agent Teams - [arxiv](https://arxiv.org/abs/2603.20380), accepted at [HAXD 2026](https://intelligent-systems.net/haxd2026/)
  964. Has your research benefited from npcpy? Let us know!
  965. ## Support
  966. [Monthly donation](https://buymeacoffee.com/npcworldwide) | [Merch](https://enpisi.com/shop) | Consulting: info@npcworldwi.de
  967. ## Contributing
  968. Contributions welcome! Submit issues and pull requests on the [GitHub repository](https://github.com/NPC-Worldwide/npcpy).
  969. ## License
  970. MIT License.
  971. ## Star History
  972. [![Star History Chart](https://star-history.dera.page/svg?repos=npc-worldwide/npcpy&type=Date)](https://star-history.dera.page/#npc-worldwide/npcpy&Date)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.