{"id":28266852,"url":"https://github.com/npc-worldwide/npcpy","last_synced_at":"2026-05-03T18:03:03.992Z","repository":{"id":257806495,"uuid":"863930645","full_name":"NPC-Worldwide/npcpy","owner":"NPC-Worldwide","description":"The python library for research and development in NLP, multimodal LLMs, Agents, ML, Knowledge Graphs, and more.","archived":false,"fork":false,"pushed_at":"2026-05-02T00:35:58.000Z","size":46379,"stargazers_count":1314,"open_issues_count":10,"forks_count":95,"subscribers_count":14,"default_branch":"main","last_synced_at":"2026-05-02T02:12:34.220Z","etag":null,"topics":["agents","ai","llm","mcp","mcp-client","mcp-server","ollama","perplexity","python","sql","yaml"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/NPC-Worldwide.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"cagostino","buy_me_a_coffee":"npcworldwide"}},"created_at":"2024-09-27T07:18:20.000Z","updated_at":"2026-05-02T00:00:20.000Z","dependencies_parsed_at":"2026-03-24T05:05:12.817Z","dependency_job_id":"3030624c-903c-4584-81d9-c8622783db32","html_url":"https://github.com/NPC-Worldwide/npcpy","commit_stats":null,"previous_names":["cagostino/npcsh","cagostino/npcpy","npc-worldwide/npcpy"],"tags_count":293,"template":false,"template_full_name":null,"purl":"pkg:github/NPC-Worldwide/npcpy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NPC-Worldwide%2Fnpcpy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NPC-Worldwide%2Fnpcpy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NPC-Worldwide%2Fnpcpy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NPC-Worldwide%2Fnpcpy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NPC-Worldwide","download_url":"https://codeload.github.com/NPC-Worldwide/npcpy/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NPC-Worldwide%2Fnpcpy/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32579089,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-03T06:36:36.687Z","status":"ssl_error","status_checked_at":"2026-05-03T06:36:09.306Z","response_time":103,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agents","ai","llm","mcp","mcp-client","mcp-server","ollama","perplexity","python","sql","yaml"],"created_at":"2025-05-20T15:04:16.837Z","updated_at":"2026-05-03T18:03:03.981Z","avatar_url":"https://github.com/NPC-Worldwide.png","language":"Python","funding_links":["https://github.com/sponsors/cagostino","https://buymeacoffee.com/npcworldwide"],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://npcpy.readthedocs.io/\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/cagostino/npcpy/main/npcpy/npc-python.png\" alt=\"npc-python logo\" width=250\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n# npcpy\n\n`npcpy` is a library that provides key functional primitives for conducting research in multimodal language models, agentic AI, and knowledge graphs. This flexible framework makes it easy to develop and engineer powerful AI applications, with support for local (`ollama`, `llama.cpp`, `omlx`, `LM Studio`) and cloud providers. Build multi-agent teams and simplify your context engineering through the NPC Context-Agent-Tool data layer with compliance engineered natively rather than an afterthought.\n\n```bash\npip install npcpy\n```\n\n## Quick Examples\n\n### Create and use personas\n\n```python\nfrom npcpy import NPC\n\nsimon = NPC(\n    name='Simon Bolivar',\n    primary_directive='Liberate South America from the Spanish Royalists.',\n    model='qwen3.5:9b',\n    provider='ollama'\n)\nresponse = simon.get_llm_response(\"What is the most important territory to retain in the Andes?\")\nprint(response['response'])\n```\n```\nMy 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. \nTo 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. \nThe 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.\n*Long live the liberty of the Andes!*\n```\n\n### Direct LLM call\n\n```python\nfrom npcpy import get_llm_response\n\n\nresponse = 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')\nprint(response['response'])\n```\n```\nCú 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.\n```\n```python\n# try ollama's cloud models\nalicanto_test = get_llm_response('what does alicanto the bird show travelers in the night?', model='minimax-m2.7:cloud', provider='ollama',)\n\nprint(alicanto_test['response'])\n```\n```\nThe legend of the **Alicanto** says that at night the bird’s feathers glow like lanterns. \nWhen a traveler sees that soft, phosphorescent light, it isn’t just a pretty sight – it’s a sign‑post. \nThe bird **shows the way to hidden water (and sometimes to buried silver or gold)** in the Atacama Desert.\n```\n\n### Agent with tools\nThe `Agent` class in `npcpy` comes with a set of default tools (sh, python, edit_file, web_search, etc.)\n\n```python\nfrom npcpy import Agent\nagent = Agent(name='File Operator', model='qwen3.5:2b', provider='ollama')\nprint(agent.run(\"Find all Python files over 500 lines in this repo and list them\"))\n```\n```\nThe following Python files contain more than 500 lines:\n - `./npcpy/npc_sysenv.py` (1486 lines)\n - `./npcpy/memory/knowledge_graph.py` (1449 lines)\n - `./npcpy/memory/kg_vis.py` (767 lines)\n - `./npcpy/memory/kg_population.py` (618 lines)\n...\n```\n\n### ToolAgent \n\nAttach custom tools to a `ToolAgent`. \nHere is an example which lets an agent generate images, fine-tune diffusion models, and then use the fine-tuned models for generation.\n\n```python\nfrom npcpy import ToolAgent, gen_image\nfrom npcpy.ft.diff import train_diffusion, generate_image, DiffusionConfig\nfrom datasets import load_dataset\nimport os\n\ndef fetch_image_dataset(dataset_name: str, split: str = \"train\", max_images: int = 100) -\u003e list:\n    \"\"\"Fetch images from a HuggingFace dataset.\n    \n    Args:\n        dataset_name: HuggingFace dataset name (e.g., 'cifar10', 'oxford-iiit-pet')\n        split: Dataset split to use\n        max_images: Maximum number of images to fetch\n    \n    Returns:\n        List of paths to saved images\n    \"\"\"\n    dataset = load_dataset(dataset_name, split=f\"{split}[:{max_images}]\")\n    os.makedirs(\"training_images\", exist_ok=True)\n    image_paths = []\n    \n    for i, item in enumerate(dataset):\n        if 'image' in item:\n            img = item['image']\n        elif 'img' in item:\n            img = item['img']\n        else:\n            continue\n        path = f\"training_images/img_{i:04d}.png\"\n        img.save(path)\n        image_paths.append(path)\n    \n    return image_paths\n\ndef finetune_diffusion_model(\n    image_paths: list,\n    captions: list = None,\n    output_path: str = \"my_diffusion_model\",\n    num_epochs: int = 50,\n) -\u003e str:\n    \"\"\"Fine-tune a diffusion model on a set of images.\n    \n    Args:\n        image_paths: List of paths to training images\n        captions: Optional captions for each image\n        output_path: Where to save the trained model\n        num_epochs: Number of training epochs\n    \n    Returns:\n        Path to the trained model\n    \"\"\"\n    if captions is None:\n        captions = [\"an image\"] * len(image_paths)\n    \n    config = DiffusionConfig(\n        image_size=64,\n        channels=128,\n        num_epochs=num_epochs,\n        batch_size=8,\n        learning_rate=1e-4,\n        checkpoint_frequency=10,\n        output_model_path=output_path,\n    )\n    \n    model_path = train_diffusion(image_paths, captions, config=config)\n    return model_path\n\n# Create an agent with image generation and fine-tuning capabilities\ncreative_agent = ToolAgent(\n    name='creative_diffusion',\n    primary_directive=\"\"\"\n        You help users generate images and fine-tune diffusion models.\n        You can: 1) Generate images using gen_image() with various prompts,\n        2) Fetch image datasets from HuggingFace,\n        3) Fine-tune diffusion models on custom image sets.\n        When a user submits an image or describes a style they like,\n        offer to fetch similar images from a dataset and fine-tune a model.\n    \"\"\",\n    tools=[fetch_image_dataset, finetune_diffusion_model, gen_image],\n    model='qwen3.5:2b',\n    provider='ollama'\n)\n\n# Example 1: Generate images\nprint(creative_agent.run(\"Generate 3 images of geometric patterns with circles and triangles\"))\n\n# Example 2: User submits an image and wants similar ones\n# The agent can fetch a dataset of patterns and fine-tune a model\nprint(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?\"))\n```\n\n### CodingAgent — auto-executes code blocks from LLM responses\n```python\nfrom npcpy import CodingAgent\n\ncoder = CodingAgent(name='coder', language='python', model='qwen3.5:2b', provider='ollama')\nprint(coder.run(\"Write a script that finds duplicate files by hash in the current directory\"))\n\n```\n```\n#The script has been created and executed successfully. Here's a summary of the findings:\n\n## Duplicate Files Found\n\n| Group | Hash (truncated) | Size | Files |\n|-------|------------------|------|-------|\n| 1 | `2b517326bf7c31b7...` | 81 bytes | `npcpy/main.py` ↔ `build/lib/npcpy/main.py` |\n| 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` |\n| 4 | `a5059f37eb682a16...` | 747 bytes | SQL files in `examples/factory/` ↔ `examples/npc_team/factory/` |\n```\n\n\n```\n\n### Multi-Agent Debate with NPCArray\n\nTo run a true multi-agent debate where agents react to each other's responses:\n\n```python\nfrom npcpy.npc_compiler import NPC\nfrom npcpy.npc_array import NPCArray\n\n# Create a debate team with role-based personas\nroles = [\n    (\"MathSolver\", \"You are a meticulous math solver. Show all steps clearly.\"),\n    (\"Skeptic\", \"You critically check for errors and assumptions.\"),\n    (\"Analyst\", \"You identify the core mathematical structure.\"),\n    (\"Verifier\", \"You confirm the final answer is correct.\")\n]\n\nnpcs = [\n    NPC(name=role, primary_directive=directive, model=\"qwen3.5:cloud\", provider=\"ollama\")\n    for role, directive in roles\n]\n\nteam = NPCArray.from_npcs(npcs)\n\n# Run parallel debate on a complex problem\nproblem = \"GSM8k: James buys a jar of hot sauce with 5 peppers and triples the peppers every year. How many after 4 years?\"\n\n# Get initial responses in parallel (one prompt per NPC)\ninitial_responses = team.infer(f\"Solve this problem:\\n{problem}\").collect()\n\nfor npc, response in zip(npcs, initial_responses.data):\n    print(f\"[{npc.name}] {response[:200]}...\")\n\n# True debate: each agent gets a personalized prompt with other agents' responses\ndef create_debate_prompt(previous_responses, my_idx, agent_name, problem_text):\n    \"\"\"Create a personalized debate prompt for a specific agent\"\"\"\n    my_response = previous_responses[my_idx]\n    other_responses = [\n        f\"[{npcs[j].name}]: {previous_responses[j][:500]}\" \n        for j in range(len(npcs)) if j != my_idx\n    ]\n    debate_prompt = f\"\"\"Original problem: {problem_text}\n\n        Your previous response: {my_response[:300]}...\n        \n        Other agents\\' responses:\"\"\" + \"\\n\\n\".join(other_responses) + \"\"\"\n        Critique the other approaches. Did they make different assumptions?\n        What did they see that you missed? Refine your solution.\"\"\"\n\n    return debate_prompt\n# Debate rounds\nresponses_data = initial_responses.data.tolist()\nproblem_text = problem\n\nfor round_num in range(3):\n    print(f\"\\n=== Debate Round {round_num + 1} ===\")\n    \n    # Create personalized prompts for each agent\n    personalized_prompts = [\n        create_debate_prompt(responses_data, i, npcs[i].name, problem_text)\n        for i in range(len(npcs))\n    ]\n    \n    # Run inference with different prompts per agent\n    # Shape: (n_models, n_prompts) - extract diagonal for each agent's response to its own prompt\n    responses = team.infer(personalized_prompts).collect()\n    \n    # Extract each model's response to its own personalized prompt\n    responses_data = [responses.data[i, i] for i in range(len(npcs))]\n    \n    # Print each agent's refined response\n    for i, npc in enumerate(npcs):\n        response = responses_data[i]\n        print(f\"[{npc.name}] {response[:200]}...\")\n\n# Alternative: use reduce to get consensus\nconsensus = team.infer(responses_data[0]).consensus(axis=0).collect()\nprint(f\"\\nFinal consensus: {consensus.data[0][:500]}...\")\n```\n\nFor iterative refinement (same prompt to all agents, updating each round):\n\n```python\n# Simple chain refinement: all agents see same synthesis\nfrom npcpy.npc_array import NPCArray\n\ndef synthesis_round(all_responses):\n    return f\"\"\"Given these perspectives:\n{chr(10).join([f'- {r[:200]}...' for r in all_responses])}\n\nRe-solve the problem incorporating insights from all approaches.\"\"\"\n\n# Chain runs the synthesis function on all responses, then feeds result back\nrefined = team.infer(f\"Solve: {problem}\").chain(\n    synthesis_round, \n    n_rounds=3\n).collect()\n```\n\n### Knowledge Graph with Sleep/Dream Lifecycle\n\n```python\nfrom npcpy.memory.knowledge_graph import (\n    kg_initial, kg_evolve_incremental, kg_sleep_process, kg_dream_process\n)\nfrom npcpy.llm_funcs import get_llm_response\n\n# Initialize KG from text corpus\ncontent_text = \"\"\"Pirate Prentice is in the lavatory stands pissing. Then he threads himself into a wool robe he wears inside out.\nThe day feels like rain.\"\"\"\n\nkg = kg_initial(content_text, model=\"gemma3:4b\", provider=\"ollama\")\n\n# Evolve with new content\nnew_content = \"\"\"The phone call, when it comes, rips easily across the room.\nPirate knows it's got to be for him.\"\"\"\n\nkg, _ = kg_evolve_incremental(kg, new_content, model=\"gemma3:4b\", provider=\"ollama\")\n\n# Sleep - consolidate and prune\nkg, sleep_report = kg_sleep_process(kg, model=\"gemma3:4b\", provider=\"ollama\")\n\n# Dream - generate speculative connections\nkg, dream_report = kg_dream_process(kg, model=\"gemma3:4b\", provider=\"ollama\", num_seeds=3)\n\nprint(f\"KG has {len(kg['facts'])} facts and {len(kg['concepts'])} concepts\")\n```\n\n### Flask Serving for NPC Teams\n\n```python\nfrom npcpy.serve import start_flask_server\nimport os\n\n# Serve your NPC team via REST API\nif __name__ == \"__main__\":\n    is_dev = not getattr(os.sys, 'frozen', False)\n    port = os.environ.get('INCOGNIDE_PORT', '5437' if is_dev else '5337')\n    frontend_port = os.environ.get('FRONTEND_PORT', '7337' if port == '5437' else '6337')\n\n    start_flask_server(\n        port=port,\n        cors_origins=f\"localhost:{frontend_port}\",\n        db_path=os.path.expanduser('~/npcsh_history.db'),\n        user_npc_directory=os.path.expanduser('~/.npcsh/npc_team'),\n        debug=False\n    )\n```\n\n### Streaming\n\n```python\nfrom npcpy import get_llm_response\nfrom npcpy.streaming import parse_stream_chunk\n\nresponse = get_llm_response(\"Explain quantum entanglement.\", model='qwen3.5:2b', provider='ollama', stream=True)\nfor chunk in response['response']:\n    content, _, _ = parse_stream_chunk(chunk, provider='ollama')\n    if content:\n        print(content, end='', flush=True)\n\n# Works the same with any provider\nresponse = get_llm_response(\"Explain quantum entanglement.\", model='gemini-2.5-flash', provider='gemini', stream=True)\nfor chunk in response['response']:\n    content, _, _ = parse_stream_chunk(chunk, provider='gemini')\n    if content:\n        print(content, end='', flush=True)\n```\n\n### JSON output\n\nInclude the expected JSON structure in your prompt. With `format='json'`, the response is auto-parsed — `response['response']` is already a dict or list.\n\n```python\nfrom npcpy import get_llm_response\n\nresponse = get_llm_response(\n    '''List 3 planets from the sun.\n    Return JSON: {\"planets\": [{\"name\": \"planet name\", \"distance_au\": 0.0, \"num_moons\": 0}]}''',\n    model='qwen3.5:2b', provider='ollama',\n    format='json'\n)\nfor planet in response['response']['planets']:\n    print(f\"{planet['name']}: {planet['distance_au']} AU, {planet['num_moons']} moons\")\n\nresponse = get_llm_response(\n    '''Analyze this review: 'The battery life is amazing but the screen is too dim.'\n    Return JSON: {\"tone\": \"positive/negative/mixed\", \"key_phrases\": [\"phrase1\", \"phrase2\"], \"confidence\": 0.0}''',\n    model='qwen3.5:2b', provider='ollama',\n    format='json'\n)\nresult = response['response']\nprint(result['tone'], result['key_phrases'])\n```\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003ePydantic structured output\u003c/b\u003e\u003c/summary\u003e\n\nPass a Pydantic model and the JSON schema is sent to the LLM directly.\n\n```python\nfrom npcpy import get_llm_response\nfrom pydantic import BaseModel\nfrom typing import List\n\nclass Planet(BaseModel):\n    name: str\n    distance_au: float\n    num_moons: int\n\nclass SolarSystem(BaseModel):\n    planets: List[Planet]\n\nresponse = get_llm_response(\n    \"List the first 4 planets from the sun.\",\n    model='qwen3.5:2b', provider='ollama',\n    format=SolarSystem\n)\nfor p in response['response']['planets']:\n    print(f\"{p['name']}: {p['distance_au']} AU, {p['num_moons']} moons\")\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eImage, audio, and video generation\u003c/b\u003e\u003c/summary\u003e\n\n```python\nfrom npcpy.llm_funcs import gen_image, gen_video\nfrom npcpy.gen.audio_gen import text_to_speech\n\n# Image — OpenAI, Gemini, Ollama, or diffusers\nimages = gen_image(\"A sunset over the mountains\", model='gemma3:4b', provider='ollama')\nimages[0].save(\"sunset.png\")\n\n# Audio — OpenAI, Gemini, ElevenLabs, Kokoro, gTTS\naudio_bytes = text_to_speech(\"Hello from npcpy!\", engine=\"gtts\")\nwith open(\"hello.wav\", \"wb\") as f:\n    f.write(audio_bytes)\n\n# Video — Gemini Veo\nresult = gen_video(\"A cat riding a skateboard\", model='veo-3.1-fast-generate-preview', provider='gemini')\nprint(result['output'])\n```\n\n\u003c/details\u003e\n\n### Multi-agent team\n\n```python\nfrom npcpy import NPC, Team\n\nteam = Team(team_path='./npc_team')\nresult = team.orchestrate(\"Analyze the latest sales data and draft a report\")\nprint(result['output'])\n```\n\nOr define a team in code:\n\n```python\nfrom npcpy import NPC, Team\n\ncoordinator = NPC(name='lead', primary_directive='Coordinate the team. Delegate to @analyst and @writer.')\nanalyst = NPC(name='analyst', primary_directive='Analyze data. Provide numbers and trends.', model='gemini-2.5-flash', provider='gemini')\nwriter = NPC(name='writer', primary_directive='Write clear reports from analysis.', model='qwen3:8b', provider='ollama')\n\nteam = Team(npcs=[coordinator, analyst, writer], forenpc='lead')\nresult = team.orchestrate(\"What are the trends in renewable energy adoption?\")\nprint(result['output'])\n```\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eTeam from files — .npc, .jinx, team.ctx\u003c/b\u003e\u003c/summary\u003e\n\n**team.ctx:**\n```yaml\ncontext: |\n  Research team for analyzing scientific literature.\n  The lead delegates to specialists as needed.\nforenpc: lead\nmodel: qwen3.5:2b\nprovider: ollama\noutput_format: markdown\nmax_search_results: 5\nmcp_servers:\n  - path: ~/.npcsh/mcp_server.py\n```\n\n**lead.npc:**\n```yaml\n#!/usr/bin/env npc\nname: lead\nprimary_directive: |\n  You lead the research team. Delegate literature searches to @searcher,\n  data analysis to @analyst. Synthesize their findings into a coherent summary.\njinxes:\n  - {{ Jinx('sh') }}\n  - {{ Jinx('python') }}\n  - {{ Jinx('delegate') }}\n  - {{ Jinx('web_search') }}\n```\n\n**searcher.npc:**\n```yaml\n#!/usr/bin/env npc\nname: searcher\nprimary_directive: |\n  You search for scientific papers and extract key findings.\n  Use web_search and load_file to find and read papers.\nmodel: gemini-2.5-flash\nprovider: gemini\njinxes:\n  - {{ Jinx('web_search') }}\n  - {{ Jinx('load_file') }}\n  - {{ Jinx('sh') }}\n```\n\n**Jinxes can reference a specific NPC** to always run under that persona, and **access `ctx` variables** from `team.ctx`:\n\n**jinxes/search_and_summarize.jinx:**\n```yaml\n#!/usr/bin/env npc\njinx_name: search_and_summarize\ndescription: Search for papers and summarize findings using the searcher NPC.\nnpc: {{ NPC('searcher') }}\ninputs:\n  - query\nsteps:\n  - name: search\n    engine: natural\n    code: |\n      Search for papers about {{ query }}.\n      Return up to {{ ctx.max_search_results }} results.\n  - name: summarize\n    engine: natural\n    code: |\n      Summarize the findings in {{ ctx.output_format }} format:\n      {{ output }}\n```\n\nThe `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.\n\n```\nmy_project/\n├── npc_team/\n│   ├── team.ctx\n│   ├── lead.npc\n│   ├── searcher.npc\n│   ├── analyst.npc\n│   ├── jinxes/\n│   │   └── skills/\n│   └── models/\n├── agents.md             # Optional: define agents in markdown\n└── agents/               # Optional: one .md file per agent\n    └── translator.md\n```\n\n`.npc` and `.jinx` files are directly executable:\n```bash\n./npc_team/lead.npc \"summarize the latest arxiv papers on transformers\"\n./npc_team/jinxes/lib/sh.jinx bash_command=\"echo hello\"\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eMCP server integration\u003c/b\u003e\u003c/summary\u003e\n\nAdd MCP servers to your team for external tool access:\n\n**team.ctx:**\n```yaml\nforenpc: assistant\nmcp_servers:\n  - path: ./tools/db_server.py\n  - path: ./tools/api_server.py\n```\n\n**db_server.py:**\n```python\nfrom mcp.server.fastmcp import FastMCP\n\nmcp = FastMCP(\"Database Tools\")\n\n@mcp.tool()\ndef query_orders(customer_id: str, limit: int = 10) -\u003e str:\n    \"\"\"Query recent orders for a customer.\"\"\"\n    # Your database logic here\n    return f\"Found {limit} orders for customer {customer_id}\"\n\n@mcp.tool()\ndef search_products(query: str) -\u003e str:\n    \"\"\"Search the product catalog.\"\"\"\n    return f\"Products matching: {query}\"\n\nif __name__ == \"__main__\":\n    mcp.run()\n```\n\nThe team's NPCs automatically get access to MCP tools alongside their jinxes.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eAgent definitions in markdown \u0026amp; Skills\u003c/b\u003e\u003c/summary\u003e\n\n**agents.md** — multiple agents in one file:\n```markdown\n## summarizer\nYou summarize long documents into concise bullet points.\nFocus on key findings, methodology, and conclusions.\n\n## fact_checker\nYou verify claims against reliable sources and flag inaccuracies.\nAlways cite your sources.\n```\n\n**agents/translator.md** — one file per agent with optional frontmatter:\n```markdown\n---\nmodel: gemini-2.5-flash\nprovider: gemini\n---\nYou translate content between languages while preserving tone and idiom.\n```\n\nSkills are knowledge-content jinxes that provide instructional sections to agents on demand.\n\n**npc_team/jinxes/skills/code-review/SKILL.md:**\n```markdown\n---\nname: code-review\ndescription: Use when reviewing code for quality, security, and best practices.\n---\n# Code Review Skill\n\n## checklist\n- Check for security vulnerabilities (SQL injection, XSS, etc.)\n- Verify error handling and edge cases\n- Review naming conventions and code clarity\n\n## security\nFocus on OWASP top 10 vulnerabilities...\n```\n\nReference in your NPC:\n```yaml\njinxes:\n  - {{ Jinx('skills/code-review') }}\n```\n\n\u003c/details\u003e\n\n### CLI tools\n\n```bash\n# The NPC shell — the recommended way to use NPC teams\nnpcsh                        # Interactive shell with agents, tools, and jinxes\n\n# Scaffold a new team\nnpc-init\n\n# Launch AI coding tools as an NPC from your team\nnpc-claude --npc corca       # Claude Code\nnpc-codex --npc analyst      # Codex\nnpc-gemini                   # Gemini CLI (interactive picker)\nnpc-opencode / npc-aider / npc-amp\n\n# Register MCP server + hooks for deeper integration\nnpc-plugin claude\n```\n\n### NPCArray — parallel jinx across multiple NPCs\n\nRun any jinx in parallel across a list of NPC instances and collect results as an array:\n\n```python\nfrom npcpy import NPC\nfrom npcpy.npc_array import NPCArray\n\n# Three NPCs with different models/providers\nnpcs = [\n    NPC(name='gramsci_1930', primary_directive='''\n        You are Antonio Gramsci writing in his Prison Notebook in 1930.\n        Defend the concept of hegemony as the predominance of one social group\n        over others through cultural and ideological leadership rather than\n        mere force. Argue that consent is more durable than coercion.\n    ''', model='qwen3:4b', provider='ollama'),\n    NPC(name='critic_1970', primary_directive='''\n        You are a post-structuralist critic in 1970 responding to Gramsci.\n        Question whether hegemony can truly explain contemporary power structures\n        or if it relies on an outdated base-superstructure model that\n        underestimates the autonomy of cultural production.\n    ''', model='qwen3:4b', provider='ollama'),\n    NPC(name='historian_present', primary_directive='''\n        You are a contemporary historian with access to the complete Prison\n        Notebooks and subsequent scholarship. Evaluate both Gramsci's original\n        formulation and the post-structuralist critique in light of the\n        collapse of actually existing socialism and the rise of neoliberalism.\n    ''', model='qwen3:4b', provider='ollama'),\n]\n\narr = NPCArray.from_npcs(npcs)\n\n# Run the same jinx on all three in parallel, collect results\nresults = 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()\nfor npc, result in zip(npcs, results.data):\n    print(f\"[{npc.name}] {result}\")\n```\n\nYou can also pass a list directly to `jinx.execute()`:\n\n```python\nfrom npcpy.npc_compiler import load_jinx_from_file\n\njinx = load_jinx_from_file('npc_team/jinxes/analyze.jinx')\nresults = jinx.execute({'topic': 'rate limiting'}, npc=npcs)  # list → parallel NPCArray run\n```\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eKnowledge graphs\u003c/b\u003e\u003c/summary\u003e\n\nBuild, evolve, and search knowledge graphs from text. The KG grows through waking (assimilation), sleeping (consolidation), and dreaming (speculative synthesis).\n\n```python\nfrom npcpy.memory.knowledge_graph import (\n    kg_initial, kg_evolve_incremental, kg_sleep_process,\n    kg_dream_process, kg_hybrid_search,\n)\n\n# Seed the KG with Gramsci's Prison Notebooks\nkg = kg_initial(\n    content=\"\"\"\n        The crisis consists precisely in the fact that the old is dying and the new\n        cannot be born. In this interregnum a great variety of morbid symptoms appear.\n        The traditional ruling class has lost its consensus, that is, the consent of\n        those over whom it rules. Force alone is not sufficient; what is needed is the\n        construction of a new hegemony, the creation of a new collective will.\n    \"\"\",\n    model=\"qwen3:4b\", provider=\"ollama\",\n)\n\n# Assimilate more content on organic vs traditional intellectuals\nkg, _ = kg_evolve_incremental(\n    kg,\n    new_content_text=\"\"\"\n        The distinction between organic and traditional intellectuals is fundamental.\n        Traditional intellectuals conceive of themselves as autonomous from ruling\n        groups, yet every social group has its own category of organic intellectuals\n        that give it homogeneity and awareness of its own function. The organic\n        intellectual emerges from within the class itself, while the traditional\n        sees himself as existing above the social structure.\n    \"\"\",\n    model=\"qwen3:4b\", provider=\"ollama\", get_concepts=True,\n)\n\n# Consolidate — merge redundant nodes, strengthen high-frequency edges\nkg, sleep_report = kg_sleep_process(kg, model=\"qwen3:4b\", provider=\"ollama\")\n\n# Dream — generate speculative connections between loosely related concepts\nkg, dream_report = kg_dream_process(kg, model=\"qwen3:4b\", provider=\"ollama\")\n\n# Search across facts, concepts, and speculative edges\nresults = kg_hybrid_search(kg, \"What constitutes hegemony in Gramsci's framework?\",\n                           model=\"qwen3:4b\", provider=\"ollama\")\nfor r in results:\n    print(r['score'], r['text'])\nprint(f\"{len(kg['facts'])} facts, {len(kg['concepts'])} concepts\")\n```\n\nExtract structured memories:\n\n```python\nfrom npcpy.llm_funcs import get_facts\n\nprison_notebooks = \"\"\"\n    Civil society is the sphere of hegemony, the terrain where the dominant\n    group exercises consent through cultural and ideological leadership.\n    Unlike political society which operates through coercion and state apparatus,\n    civil society comprises the church, schools, trade unions, and media.\n    The ruling class maintains power not merely through force but through the\n    production of consent, shaping common sense itself through cultural institutions.\n    War of position requires patient trench warfare on this terrain, building\n    counter-hegemonic institutions rather than frontal assault on the state.\n\"\"\"\n\nfacts = get_facts(prison_notebooks, model=\"qwen3:4b\", provider=\"ollama\")\nfor f in facts:\n    print(f\"[{f.get('type', 'general')}] {f['statement']}\")\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eSememolution — population-based KG evolution\u003c/b\u003e\u003c/summary\u003e\n\nMaintain 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.\n\n```python\nfrom npcpy.memory.kg_population import SememolutionPopulation\n\npop = SememolutionPopulation(population_size=100, sample_size=10)\npop.initialize()\n\npop.assimilate_text(\"\"\"\n    The debate over lunar resource extraction has intensified since the discovery\n    of water ice in permanently shadowed regions at the lunar poles. While some\n    researchers argue that commercial mining could fund further exploration,\n    others warn that unregulated extraction could contaminate scientifically\n    valuable sites that have remained pristine for billions of years. The\n    Artemis Accords attempt to establish a framework for international\n    cooperation, but major spacefaring nations have yet to reach consensus\n    on property rights and environmental protection standards.\n\"\"\")\npop.assimilate_text(\"\"\"\n    Tidal acceleration gradually increases the orbital distance between Earth\n    and Moon at a rate of approximately 3.8 centimeters per year. This\n    phenomenon results from angular momentum transfer via gravitational\n    interaction, simultaneously slowing Earth's rotation and lengthening the\n    day. Paleontological evidence from tidal rhythmites suggests that 620\n    million years ago, a day lasted only 21.9 hours and the lunar month was\n    just 27.5 days. Projections indicate that in approximately 600 million\n    years, tidal effects will no longer support total solar eclipses.\n\"\"\")\n\n# Sleep/dream cycle — each individual consolidates according to its genome\npop.sleep_cycle()\n\n# Query: sample 10 individuals, generate competing responses, rank them\nrankings = pop.query_and_rank(\"What are the central themes connecting these documents?\")\nfor rank, entry in enumerate(rankings[:3], 1):\n    print(f\"#{rank} (individual {entry['id']}, score {entry['score']:.3f}): {entry['response'][:120]}...\")\n\n# Selection + reproduction — top performers breed, bottom are replaced\npop.evolve_generation()\n\nstats = pop.get_stats()\nprint(f\"Generation {stats['generation']} | avg fitness {stats['avg_fitness']:.3f} | \"\n      f\"best fitness {stats['best_fitness']:.3f} | diversity {stats['diversity']:.3f}\")\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eFine-tuning (SFT, RL, MLX)\u003c/b\u003e\u003c/summary\u003e\n\n**RL Training with DPO for Tool-Calling Agents**\n\n```python\nfrom npcpy.npc_compiler import NPC\nfrom npcpy.ft.rl import RLConfig, train_with_dpo, load_rl_model\nimport json\n\ndef npcsh_reward(trace):\n    \"\"\"Reward function for shell assistant responses.\"\"\"\n    output = trace.get('final_output', '')\n    completed = trace.get('completed', False)\n    score = 0.0\n    if completed:\n        score += 2.0\n    if 50 \u003c len(output) \u003c 1500:\n        score += 1.0\n    if '```' in output:\n        score += 1.0\n    if any(cmd in output.lower() for cmd in ['ls', 'cd', 'cat', 'grep', 'find', 'pip', 'git']):\n        score += 0.3\n    return max(0.0, min(10.0, score + 5.0))\n\n# Load preference pairs from agent traces\ntraces = []\nwith open('preference_pairs.jsonl', 'r') as f:\n    for line in f:\n        pair = json.loads(line)\n        traces.append({\n            'task_prompt': pair['prompt'],\n            'final_output': pair['chosen'],\n            'reward': pair.get('chosen_score', 8.0),\n            'completed': True\n        })\n        traces.append({\n            'task_prompt': pair['prompt'],\n            'final_output': pair['rejected'],\n            'reward': pair.get('rejected_score', 3.0),\n            'completed': False\n        })\n\nconfig = RLConfig(\n    base_model_name=\"Qwen/Qwen2.5-0.5B-Instruct\",\n    adapter_path=\"./npcsh_adapter\",\n    num_train_epochs=3,\n    per_device_train_batch_size=2,\n    learning_rate=5e-5,\n    beta=0.1\n)\n\nadapter_path = train_with_dpo(traces, config)\nprint(f\"Trained adapter saved to: {adapter_path}\")\n```\n\n**SFT for Scientific Writing Style Transfer**\n\n```python\nfrom npcpy.llm_funcs import get_llm_response\nfrom npcpy.ft.sft import SFTConfig, run_sft\n\n# Generate scientific writing dataset from style samples\ndef generate_scientific_trace(question, reasoning_model, converter_model, style_chunks):\n    \"\"\"Generate native reasoning then rewrite in scientific voice.\"\"\"\n    # Step 1: Get reasoning trace\n    native_prompt = f\"\"\"Answer this question with detailed reasoning.\nQuestion: {question}\nProvide your step-by-step reasoning and final answer.\"\"\"\n    native_response = get_llm_response(native_prompt, model=reasoning_model, provider='ollama')\n    native_trace = native_response['response']\n\n    # Step 2: Rewrite in scientific style\n    style_context = '\\n\\n---\\n\\n'.join(style_chunks[:8])\n    rewrite_prompt = f\"\"\"Rewrite the following reasoning trace in the scientific writing style demonstrated by the excerpts below.\nOriginal Reasoning Trace:\n{native_trace}\n\nSCIENTIFIC PAPER EXCERPTS:\n{style_context}\n\nTask:\n1. Rewrite the reasoning in the style of the scientific paper excerpts\n2. Use LaTeX notation where appropriate\n3. Preserve the logical flow and factual content\n4. Match the prose density and intellectual register\"\"\"\n\n    rewritten = get_llm_response(rewrite_prompt, model=converter_model, provider='ollama')\n    return rewritten['response']\n\n# Train on generated examples\nX_train = [\"What is the relationship between quantum contextuality and natural language interpretation?\"]\ny_train = [generate_scientific_trace(X_train[0], 'qwen3:8b', 'qwen3:8b', style_chunks)]\n\nsft_config = SFTConfig(\n    base_model_name=\"Qwen/Qwen3-4B\",\n    output_model_path=\"models/scientific-writer\",\n    device='mlx',\n    num_train_epochs=100,\n    per_device_train_batch_size=1,\n    lora_r=128,\n    lora_alpha=256\n)\n\nmodel_path = run_sft(X_train, y_train, config=sft_config, format_style=\"llama\")\n```\n\n\u003c/details\u003e\n\n## Features\n\n- **[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)\n- **[Multi-Agent Teams](https://npcpy.readthedocs.io/en/latest/guides/teams/)** — Team orchestration with a coordinator (forenpc)\n- **[Jinx Workflows](https://npcpy.readthedocs.io/en/latest/guides/jinx-workflows/)** — Jinja Execution templates for multi-step prompt pipelines\n- **[Skills](https://npcpy.readthedocs.io/en/latest/guides/skills/)** — Knowledge-content jinxes that serve instructional sections to agents on demand\n- **[NPCArray](https://npcpy.readthedocs.io/en/latest/guides/npc-array/)** — NumPy-like vectorized operations over model populations\n- **[Image, Audio \u0026 Video](https://npcpy.readthedocs.io/en/latest/guides/image-audio-video/)** — Generation via Ollama, diffusers, OpenAI, Gemini, ElevenLabs\n- **[Knowledge Graphs](https://npcpy.readthedocs.io/en/latest/guides/knowledge-graphs/)** — Build and evolve knowledge graphs from text with sleep/dream lifecycle\n- **[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\n- **[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\n- **[Fine-Tuning \u0026 Evolution](https://npcpy.readthedocs.io/en/latest/guides/fine-tuning/)** — SFT, USFT, RL/DPO, diffusion, genetic algorithms, MLX on Apple Silicon\n- **[Serving](https://npcpy.readthedocs.io/en/latest/guides/serving/)** — Flask server for deploying teams via REST API\n- **[ML Functions](https://npcpy.readthedocs.io/en/latest/guides/ml-funcs/)** — Scikit-learn grid search, ensemble prediction, PyTorch training\n- **[Streaming \u0026 JSON](https://npcpy.readthedocs.io/en/latest/guides/llm-responses/)** — Streaming responses, structured JSON output, message history\n\n## Providers\n\nWorks with all major LLM providers through LiteLLM: `ollama`, `openai`, `anthropic`, `gemini`, `deepseek`, `airllm`, `openai-like`, and more.\n\n## Installation\n\n```bash\npip install npcpy              # base\npip install npcpy[lite]        # + API provider libraries\npip install npcpy[local]       # + ollama, diffusers, transformers, airllm\npip install npcpy[yap]         # + TTS/STT\npip install npcpy[all]         # everything\n```\n\n\u003cdetails\u003e\u003csummary\u003eSystem dependencies\u003c/summary\u003e\n\n**Linux:**\n```bash\nsudo apt-get install espeak portaudio19-dev python3-pyaudio ffmpeg libcairo2-dev libgirepository1.0-dev\ncurl -fsSL https://ollama.com/install.sh | sh\nollama pull qwen3.5:2b\n```\n\n**macOS:**\n```bash\nbrew install portaudio ffmpeg pygobject3 ollama\nbrew services start ollama\nollama pull qwen3.5:2b\n```\n\n**Windows:** Install [Ollama](https://ollama.com) and [ffmpeg](https://ffmpeg.org), then `ollama pull qwen3.5:2b`.\n\n\u003c/details\u003e\n\nAPI keys go in a `.env` file:\n```bash\nexport OPENAI_API_KEY=\"your_key\"\nexport ANTHROPIC_API_KEY=\"your_key\"\nexport GEMINI_API_KEY=\"your_key\"\n```\n\n## Read the Docs\n\nFull documentation, guides, and API reference at [npcpy.readthedocs.io](https://npcpy.readthedocs.io/en/latest/).\n\n## Links\n\n- **[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))\n- **[NPC Shell](https://github.com/npc-worldwide/npcsh)** — Command-line shell for interacting with NPCs\n- **[Newsletter](https://forms.gle/n1NzQmwjsV4xv1B2A)** — Stay in the loop\n\n## Research\n\n- A Quantum Semantic Framework for natural language processing: [arxiv](https://arxiv.org/abs/2506.10077), accepted at [QNLP 2025](https://qnlp.ai)\n- Simulating hormonal cycles for AI: [arxiv](https://arxiv.org/abs/2508.11829)\n- TinyTim: A Family of Language Models for Divergent Generation [arxiv](https://arxiv.org/abs/2508.11607)\n- The production of meaning in the processing of natural language: [arxiv](https://arxiv.org/abs/2603.20381)\n- ALARA for Agents: Least-Privilege Context Engineering Through Portable Composable Multi-Agent Teams: [arxiv](https://arxiv.org/abs/2603.20380)\n\nHas your research benefited from npcpy? Let us know!\n\n## Support\n\n[Monthly donation](https://buymeacoffee.com/npcworldwide) | [Merch](https://enpisi.com/shop) | Consulting: info@npcworldwi.de\n\n## Contributing\n\nContributions welcome! Submit issues and pull requests on the [GitHub repository](https://github.com/NPC-Worldwide/npcpy).\n\n## License\n\nMIT License.\n\n## Star History\n\n[![Star History Chart](https://api.star-history.com/svg?repos=cagostino/npcpy\u0026type=Date)](https://star-history.com/#cagostino/npcpy\u0026Date)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnpc-worldwide%2Fnpcpy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnpc-worldwide%2Fnpcpy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnpc-worldwide%2Fnpcpy/lists"}