npcpy

pip install npcpy

Quick Examples

Agent with persona

fromnpcpy.npc_compilerimportNPCsimon=NPC(name='Simon Bolivar',primary_directive='Liberate South America from the Spanish Royalists.',model='gemma3:4b',provider='ollama')response=simon.get_llm_response("What is the most important territory to retain in the Andes?")print(response['response'])

Direct LLM call

fromnpcpy.llm_funcsimportget_llm_responseresponse=get_llm_response("Who was the celtic messenger god?",model='qwen3:4b',provider='ollama')print(response['response'])

Agent with tools

importosfromnpcpy.npc_compilerimportNPCdeflist_files(directory:str=".")->list:"""List all files in a directory."""returnos.listdir(directory)defread_file(filepath:str)->str:"""Read and return the contents of a file."""withopen(filepath,'r')asf:returnf.read()assistant=NPC(name='File Assistant',primary_directive='You help users explore files.',model='llama3.2',provider='ollama',tools=[list_files,read_file],)response=assistant.get_llm_response("List the files in the current directory.")print(response['response'])# Access individual tool resultsforresultinresponse.get('tool_results', []):print(f"{result['tool_name']}:{result['result']}")

Streaming responses

fromnpcpy.llm_funcsimportget_llm_responseresponse=get_llm_response("Tell me about the history of the Inca Empire.",model='llama3.2',provider='ollama',stream=True)forchunkinresponse['response']:msg=chunk.get('message', {})print(msg.get('content',''),end='',flush=True)

JSON output

fromnpcpy.llm_funcsimportget_llm_responseresponse=get_llm_response("List 3 planets with their distances from the sun in AU.",model='llama3.2',provider='ollama',format='json')print(response['response'])

Multi-agent team orchestration

fromnpcpy.npc_compilerimportNPC,Team# Create specialist agentscoordinator=NPC(name='coordinator',primary_directive='''You coordinate a team of specialists.    Delegate tasks by mentioning @analyst for data questions or @writer for content.    Synthesize their responses into a final answer.''',model='llama3.2',provider='ollama')analyst=NPC(name='analyst',primary_directive='You analyze data and provide insights with specific numbers.',model='~/models/mistral-7b-instruct-v0.2.Q4_K_M.gguf',provider='llamacpp')writer=NPC(name='writer',primary_directive='You write clear, engaging summaries and reports.',model='gemini-2.5-flash',provider='gemini')# Create team - coordinator (forenpc) automatically delegates via @mentionsteam=Team(npcs=[coordinator,analyst,writer],forenpc='coordinator')# Orchestrate a request - coordinator decides who to involveresult=team.orchestrate("What are the trends in renewable energy adoption?")print(result['output'])

Initialize a team

# Using npc CLInpc init ./my_project# Using npcsh (interactive)npcsh📁~/projects🤖 npcsh| llama3.2> /init directory=./my_project> what files arein the current directory?

my_project/├── npc_team/│   ├── forenpc.npc      # Default coordinator│   ├── jinxs/           # Workflows│   │   └── skills/      # Knowledge skills│   ├── tools/           # Custom tools│   └── triggers/        # Event triggers├── images/├── models/└── mcp_servers/

# Add team contextcat> my_project/npc_team/team.ctx<< 'EOF'context: Research and analysis teamforenpc: leadmodel: llama3.2provider: ollamaEOF# Add agentscat> my_project/npc_team/lead.npc<< 'EOF'name: leadprimary_directive: |  You lead the team. Delegate to @researcher for data  and @writer for content. Synthesize their output.EOFcat> my_project/npc_team/researcher.npc<< 'EOF'name: researcherprimary_directive: You research topics and provide detailed findings.model: gemini-2.5-flashprovider: geminiEOFcat> my_project/npc_team/writer.npc<< 'EOF'name: writerprimary_directive: You write clear, engaging content.model: qwen3:8bprovider: ollamaEOF

Team directory structure

npc_team/├── team.ctx           # Team configuration├── coordinator.npc    # Coordinator agent├── analyst.npc        # Specialist agent├── writer.npc         # Specialist agent└── jinxs/             # Optional workflows    └── research.jinx

context:|  A research team that analyzes topics and produces reports.  The coordinator delegates to specialists as needed.forenpc:coordinatormodel:llama3.2provider:ollamamcp_servers:  -~/.npcsh/mcp_server.py

name:coordinatorprimary_directive:|  You coordinate research tasks. Delegate to @analyst for data  analysis and @writer for content creation. Synthesize results.model:llama3.2provider:ollama

name:analystprimary_directive:|  You analyze data and provide insights with specific numbers and trends.model:qwen3:8bprovider:ollama

Team from directory

fromnpcpy.npc_compilerimportTeam# Load team from directory with .npc files and team.ctxteam=Team(team_path='./npc_team')# Orchestrate through the forenpc (set in team.ctx)result=team.orchestrate("Analyze the sales data and write a summary")print(result['output'])

Agent with skills

---name:code-reviewdescription:Use when reviewing code for quality, security, and best practices.---#Code Review Skill##checklist- Check for security vulnerabilities (SQL injection, XSS, etc.)- Verify error handling and edge cases- Review naming conventions and code clarity##securityFocus on OWASP top 10 vulnerabilities...

name:reviewerprimary_directive:You review code for quality and security issues.model:llama3.2provider:ollamajinxs:  -skills/code-review

fromnpcpy.npc_compilerimportNPC# Load NPC from file - skills are automatically available as callable jinxsreviewer=NPC(file='./npc_team/reviewer.npc')response=reviewer.get_llm_response("Review this function: def login(user, pwd): ...")print(response['response'])

Agent with MCP server

fromnpcpy.npc_compilerimportNPCfromnpcpy.serveimportMCPClientNPC# Connect to your MCP servermcp=MCPClientNPC()mcp.connect_sync('./my_mcp_server.py')# Create an NPCassistant=NPC(name='Assistant',primary_directive='You help users with tasks using available tools.',model='llama3.2',provider='ollama')# Pass MCP tools to get_llm_response - the agent handles tool calls automaticallyresponse=assistant.get_llm_response("Search the database for recent orders",tools=mcp.available_tools_llm,tool_map=mcp.tool_map)print(response['response'])# Clean up when donemcp.disconnect_sync()

frommcp.server.fastmcpimportFastMCPmcp=FastMCP("My Tools")@mcp.tool()defsearch_database(query:str)->str:"""Search the database for records matching the query."""returnf"Found results for:{query}"@mcp.tool()defsend_notification(message:str,channel:str="general")->str:"""Send a notification to a channel."""returnf"Sent '{message}' to #{channel}"if__name__=="__main__":mcp.run()

Image generation

fromnpcpy.llm_funcsimportgen_imageimages=gen_image("A sunset over the mountains",model='sdxl',provider='diffusers')images[0].save("sunset.png")

Features

Providers

Installation

pip install npcpy# basepip install npcpy[lite]# + API provider librariespip install npcpy[local]# + ollama, diffusers, transformers, airllmpip install npcpy[yap]# + TTS/STTpip install npcpy[all]# everything

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

Read the Docs

Inference Capabilities

Links

Research

Support

Contributing

License

Star History