npcpy

Name: npcpy
Author: NPC-Worldwide

5.4kinstalls/mo · pypi1.4kstars106forks

How to install npcpy?

npc-worldwide/npcpy

$git clone https://github.com/NPC-Worldwide/npcpy

Installs into the current project.

Summary

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 S

Files · 1

View on GitHub

README.md

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
6	# npcpy
7
8	`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.
9	```bash
10	pip install npcpy
11	```
12
13	## Quick Examples
14
15	### Create and use personas
16
17	```python
18	from npcpy import NPC
19
20	simon = NPC(
21	name='Simon Bolivar',
22	primary_directive='''
23	Liberate South America
24	from the Spanish Royalists.
25	''',
26	model='qwen3.5:9b',
27	provider='ollama'
28	)
29	response = simon.get_llm_response("What is the most important territory to retain in the Andes?")
30	print(response['response'])
31	```
32	```
33	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.
34	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.
35	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.
36	Long live the liberty of the Andes!
37	```
38
39	### Direct LLM call
40
41	```python
42	from npcpy import get_llm_response
43
44
45	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')
46	print(response['response'])
47	```
48	```
49	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.
50	```
51	```python
52	# try ollama's cloud models
53	alicanto_test = get_llm_response('what does alicanto the bird show travelers in the night?', model='minimax-m2.7:cloud', provider='ollama',)
54
55	print(alicanto_test['response'])
56	```
57	```
58	The legend of the Alicanto says that at night the bird’s feathers glow like lanterns.
59	When a traveler sees that soft, phosphorescent light, it isn’t just a pretty sight – it’s a sign‑post.
60	The bird shows the way to hidden water (and sometimes to buried silver or gold) in the Atacama Desert.
61	```
62
63	### Agent with tools
64	The `Agent` class in `npcpy` comes with a set of default tools (sh, python, edit_file, web_search, etc.)
65
66	```python
67	from npcpy import Agent
68	agent = Agent(name='File Operator', model='qwen3.5:2b', provider='ollama')
69	print(agent.run("Find all Python files over 500 lines in this repo and list them"))
70	```
71	```
72	The following Python files contain more than 500 lines:
73	- `./npcpy/npc_sysenv.py` (1486 lines)
74	- `./npcpy/memory/knowledge_graph.py` (1449 lines)
75	- `./npcpy/memory/kg_vis.py` (767 lines)
76	- `./npcpy/memory/kg_population.py` (618 lines)
77	...
78	```
79
80	### ToolAgent
81
82	Attach custom tools to a `ToolAgent`.
83	Here is an example which lets an agent generate images, fine-tune diffusion models, and then use the fine-tuned models for generation.
84
85	```python
86	from npcpy import ToolAgent, gen_image
87	from npcpy.ft.diff import train_diffusion, gene

People who liked this also viewed

6 picks

Type

npcpy

5.4kinstalls/mo · pypi1.4kstars106forks

View on GitHub

How to install npcpy?

npc-worldwide/npcpy

$git clone https://github.com/NPC-Worldwide/npcpy

Installs into the current project.

Summary

Files · 1

View on GitHub

README.md

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
6	# npcpy
7
8	`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.
9	```bash
10	pip install npcpy
11	```
12
13	## Quick Examples
14
15	### Create and use personas
16
17	```python
18	from npcpy import NPC
19
20	simon = NPC(
21	name='Simon Bolivar',
22	primary_directive='''
23	Liberate South America
24	from the Spanish Royalists.
25	''',
26	model='qwen3.5:9b',
27	provider='ollama'
28	)
29	response = simon.get_llm_response("What is the most important territory to retain in the Andes?")
30	print(response['response'])
31	```
32	```
33	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.
34	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.
35	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.
36	Long live the liberty of the Andes!
37	```
38
39	### Direct LLM call
40
41	```python
42	from npcpy import get_llm_response
43
44
45	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')
46	print(response['response'])
47	```
48	```
49	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.
50	```
51	```python
52	# try ollama's cloud models
53	alicanto_test = get_llm_response('what does alicanto the bird show travelers in the night?', model='minimax-m2.7:cloud', provider='ollama',)
54
55	print(alicanto_test['response'])
56	```
57	```
58	The legend of the Alicanto says that at night the bird’s feathers glow like lanterns.
59	When a traveler sees that soft, phosphorescent light, it isn’t just a pretty sight – it’s a sign‑post.
60	The bird shows the way to hidden water (and sometimes to buried silver or gold) in the Atacama Desert.
61	```
62
63	### Agent with tools
64	The `Agent` class in `npcpy` comes with a set of default tools (sh, python, edit_file, web_search, etc.)
65
66	```python
67	from npcpy import Agent
68	agent = Agent(name='File Operator', model='qwen3.5:2b', provider='ollama')
69	print(agent.run("Find all Python files over 500 lines in this repo and list them"))
70	```
71	```
72	The following Python files contain more than 500 lines:
73	- `./npcpy/npc_sysenv.py` (1486 lines)
74	- `./npcpy/memory/knowledge_graph.py` (1449 lines)
75	- `./npcpy/memory/kg_vis.py` (767 lines)
76	- `./npcpy/memory/kg_population.py` (618 lines)
77	...
78	```
79
80	### ToolAgent
81
82	Attach custom tools to a `ToolAgent`.
83	Here is an example which lets an agent generate images, fine-tune diffusion models, and then use the fine-tuned models for generation.
84
85	```python
86	from npcpy import ToolAgent, gen_image
87	from npcpy.ft.diff import train_diffusion, gene

People who liked this also viewed

6 picks

Type