{"type":"mcp_server","name":"npcpy","description":"Here are a few options, prioritizing clarity and SEO:\n\n*   **AI Dev Toolkit: MCP for building & managing AI models. #AI #ML** (63 chars)\n*   **npcpy: Model Context Protocol toolkit for AI development.","category":"AI","language":"Python","stars":1445,"forks":43,"owner":"NPC-Worldwide","github_url":"https://github.com/NPC-Worldwide/npcpy","homepage":null,"setup":"## Setup\n\n`npcpy` is available on PyPI and can be installed using pip.\n\n### Prerequisites\n\nBefore installing, ensure you have the necessary dependencies installed on your system.\n\n#### Linux\n\n```bash\n# (Optional) For audio support (TTS/STT):\nsudo apt-get update\nsudo apt-get install -y espeak portaudio19-dev python3-pyaudio alsa-base alsa-utils libcairo2-dev libgirepository1.0-dev ffmpeg\n\n# (Optional) For file system triggers:\nsudo apt-get install -y inotify-tools\n\n# (Optional) If you don't have Ollama installed:\ncurl -fsSL https://ollama.com/install.sh | sh\n```\n\n#### Mac\n\n```bash\n# (Optional) For audio support:\nbrew install portaudio ffmpeg pygobject3\n\n# (Optional) For file system triggers:\nbrew install inotify-tools\n\n# (Optional) If you don't have Ollama installed:\nbrew install ollama\nbrew services start ollama\n```\n\n#### Windows\n\n1.  Download and install the Ollama executable from the [Ollama website](https://ollama.com/).\n2.  Using PowerShell, install FFmpeg:\n\n    ```powershell\n    # Instructions for installing ffmpeg with chocolatey\n    # choco install ffmpeg\n    ```\n\n### Installation Steps\n\n1.  Install `npcpy` using pip:\n\n    ```bash\n    pip install npcpy\n    ```\n\n2.  (Optional) Install with extra dependencies:\n\n    *   With API libraries:\n\n        ```bash\n        pip install 'npcpy[lite]'\n        ```\n\n    *   With full local package set up (Ollama, Diffusers, Transformers, CUDA, etc.):\n\n        ```bash\n        pip install 'npcpy[local]'\n        ```\n\n    *   For TTS/STT support:\n\n        ```bash\n        pip install 'npcpy[yap]'\n        ```\n\n    *   To install everything:\n\n        ```bash\n        pip install 'npcpy[all]'\n        ```\n\n3.  (Optional) Pull necessary models if using Ollama:\n\n    ```bash\n    ollama pull llama3.2\n    ollama pull llava:7b\n    ollama pull nomic-embed-text\n    ```\n\n### Configuration\n\n1.  Run `npcsh` for the first time to generate the `.npcshrc` file:\n\n    ```bash\n    npcsh\n    ```\n\n2.  The `.npcshrc` file will be created in your home directory (`~/.npcshrc`). This file stores your `npcsh` settings. Example:\n\n    ```bash\n    # NPCSH Configuration File\n    export NPCSH_INITIALIZED=1\n    export NPCSH_CHAT_PROVIDER='ollama'\n    export NPCSH_CHAT_MODEL='llama3.2'\n    export NPCSH_DB_PATH='~/npcsh_history.db'\n    ```\n\n3.  (Optional) Add the following lines to your `.bashrc` or `.zshrc` file to source the `npcsh` configuration:\n\n    ```bash\n    # Source NPCSH configuration\n    if [ -f ~/.npcshrc ]; then\n        . ~/.npcshrc\n    fi\n    ```\n\n### Environment Variables\n\nTo use tools that require API keys, create an `.env` file in the folder where you are working or place relevant API keys as env variables in your `~/.npcshrc`. If you already have these API keys set in a `~/.bashrc` or a `~/.zshrc` or similar files, you need not additionally add them to `~/.npcshrc` or to an `.env` file. Example `.env` file:\n\n```bash\nexport OPENAI_API_KEY=\"your_openai_key\"\nexport ANTHROPIC_API_KEY=\"your_anthropic_key\"\nexport DEEPSEEK_API_KEY='your_deepseek_key'\nexport GEMINI_API_KEY='your_gemini_key'\nexport PERPLEXITY_API_KEY='your_perplexity_key'\n```\n\nIndividual NPCs can also be set to use different models and providers by setting the `model` and `provider` keys in the NPC files.\n\n### Project Structure\n\nAfter initialization, the following directory structure will be created:\n\n```\n~/.npcsh/\n├── npc_team/           # Global NPCs\n│   ├── jinxs/          # Global tools\n│   └── assembly_lines/ # Workflow pipelines\n```\n\nFor project-specific configurations, create an `npc_team` directory in your project:\n\n```\n./npc_team/            # Project-specific NPCs\n├── jinxs/             # Project jinxs\n│   └── example.jinx\n└── assembly_lines/    # Project workflows\n    └── example.pipe\n└── models/    # Project workflows\n    └── example.model\n└── example1.npc        # Example NPC\n└── example2.npc        # Example NPC\n└── team.ctx            # Example ctx\n```","tools":"## Available Tools\n\n- **NPC (from `npcpy.npc_compiler`)**: Creates and manages AI agents with specific names, directives, models, and providers.\n    ```python\n    from npcpy.npc_compiler import NPC\n    simon = NPC(\n              name='Simon Bolivar',\n              primary_directive='Liberate South America from the Spanish Royalists.',\n              model='gemma3',\n              provider='ollama'\n              )\n    response = simon.get_llm_response(\"What is the most important territory to retain in the Andes mountains?\")\n    print(response['response'])\n    ```\n\n- **Team (from `npcpy.npc_compiler`)**: Sets up and orchestrates a team of NPCs, including a forenpc to manage the team's actions.\n    ```python\n    from npcpy.npc_compiler import NPC, Team\n    ggm = NPC(\n              name='gabriel garcia marquez',\n              primary_directive='You are the author gabriel garcia marquez. see the stars ',\n              model='deepseek-chat',\n              provider='deepseek',\n              )\n\n    isabel = NPC(\n              name='isabel allende',\n              primary_directive='You are the author isabel allende. visit the moon',\n              model='deepseek-chat',\n              provider='deepseek',\n              )\n    borges = NPC(\n              name='jorge luis borges',\n              primary_directive='You are the author jorge luis borges. listen to the earth and work with your team',\n              model='gpt-4o-mini',\n              provider='openai',\n              )          \n\n    # set up an NPC team with a forenpc that orchestrates the other npcs\n    lit_team = Team(npcs = [ggm, isabel], forenpc=borges)\n\n    print(lit_team.orchestrate('whats isabel working on? '))\n    ```\n\n- **get_llm_response (from `npcpy.llm_funcs`)**: Retrieves responses from LLMs, allowing for specification of model, provider, and formatting options. Can be used with or without an NPC agent.\n    ```python\n    from npcpy.llm_funcs import get_llm_response\n    response = get_llm_response(\"Who was the celtic Messenger god?\", model='llama3.2', provider='ollama')\n    print(response['response'])\n    ```\n    - Supports structured outputs via `format='json'` or Pydantic schemas.\n    ```python\n    from npcpy.llm_funcs import get_llm_response\n    response = get_llm_response(\"What is the sentiment of the american people towards the repeal of Roe v Wade? Return a json object with `sentiment` as the key and a float value from -1 to 1 as the value\", model='gemma3:1b', provider='ollama', format='json')\n\n    print(response['response'])\n    ```\n    - Supports streaming responses.\n    ```python\n    from npcpy.npc_sysenv import print_and_process_stream\n    from npcpy.llm_funcs import get_llm_response\n    response = get_llm_response(\"When did the united states government begin sendinng advisors to vietnam?\", model='llama3.2', provider='ollama', stream = True)\n\n    full_response = print_and_process_stream(response['response'], 'llama3.2', 'ollama')\n    ```\n    - Supports passing lists of messages for conversational context.\n    - Supports passing attachments (images) to the LLM.\n    ```python\n    from npcpy.llm_funcs import get_llm_response\n    messages = [{'role': 'system', 'content': 'You are an annoyed assistant.'}]\n\n    response = get_llm_response(\"What is the meaning of caesar salad\", model='gpt-4o-mini', provider='openai', images=['./Language_Evolution_and_Innovation_experiment.png'], messages=messages)\n    ```\n\n- **print_and_process_stream (from `npcpy.npc_sysenv`)**: Processes and prints streaming responses from LLMs.\n\n- **gen_image (from `npcpy.llm_funcs`)**: Generates images using models from Hugging Face's diffusers library, OpenAI, or Gemini.\n    ```python\n    from npcpy.llm_funcs import gen_image\n    image = gen_image(\"make a picture of the moon in the summer of marco polo\", model='runwayml/stable-diffusion-v1-5', provider='diffusers')\n\n    image = gen_image(\"make a picture of the moon in the summer of marco polo\", model='dall-e-2', provider='openai')\n\n    # edit images with 'gpt-image-1' or gemini's multimodal models, passing image paths, byte code images, or PIL instances.\n\n    image = gen_image(\"make a picture of the moon in the summer of marco polo\", model='gpt-image-1', provider='openai', attachments=['/path/to/your/image.jpg', your_byte_code_image_here, your_PIL_image_here])\n\n\n    image = gen_image(\"edit this picture of the moon in the summer of marco polo so that it looks like it is in the winter of nishitani\", model='gemini-2.0-flash', provider='gemini', attachments= [])\n    ```\n\n- **gen_video (from `npcpy.llm_funcs`)**: Generates videos using specified models and providers.\n    ```python\n    from npcpy.llm_funcs import gen_video\n    video = gen_video(\"make a video of the moon in the summer of marco polo\", model='runwayml/stable-diffusion-v1-5', provider='diffusers')\n    ```\n\n- **NPC Shell (`npcsh`)**: A bash-replacement shell that can process bash, natural language, or special macro calls.\n    - `/search`: Web searching. Example: `/search -p perplexity 'cal bears football schedule'`\n    - `/sample`: One-shot sampling. Example: `/sample 'prompt'`\n    - `/vixynt`: Image generation. Example: `/vixynt 'an image of a dog eating a hat'`\n    - Process Identification: `please identify the process consuming the most memory on my computer`\n    - `/ots`: Screenshot analysis.\n    - `/yap`: Voice chat.\n    - `/plonk`: Computer use. Example: `/plonk -n 'npc_name' -sp 'task for plonk to carry out'`\n    - `/spool`: Enter chat loop with an NPC. Example: `/spool -n <npc_name>`\n\n- **`guac`**: A replacement shell for interpreters like python/r/node/julia with an avocado input marker 🥑 that brings a pomodoro-like approach to interactive coding.\n    - Simulation: `🥑 Make a markov chain simulation of a random walk in 2D space with 1000 steps and visualize`\n    - Access variables: `🥑 print(positions)`\n    - Run a python script: `🥑 run file.py`\n    - Refresh: `🥑 /refresh`\n    - Show current variables: `🥑 /show`\n\n- **`npc` CLI**: A command-line interface offering the capabilities of the npc shell from a regular bash shell.\n  - **Ask a Generic Question**\n    ```bash\n    npc 'has there ever been a better pasta shape than bucatini?'\n    ```\n  - **Compile an NPC**\n    ```bash\n    npc compile /path/to/npc.npc\n    ```\n  - **Computer Use**\n    ```bash\n    npc plonk -n 'npc_name' -sp 'task for plonk to carry out'\n    ```\n  - **Generate Image**\n    ```bash\n    npc vixynt 'generate an image of a rabbit eating ham in the brink of dawn' model='gpt-image-1' provider='openai'\n    ```\n  - **Search the Web**\n    ```bash\n    npc search -q \"cal golden bears football schedule\" -sp perplexity\n    ```\n  - **Serve an NPC Team**\n    ```bash\n    npc serve --port 5337 --cors='http://localhost:5137/'\n    ```\n  - **Screenshot Analysis**\n    ```bash\n    npc ots\n    ```\n\n- **`alicanto`**: A research exploration agent flow.\n    - Example: `npc alicanto \"What are the implications of quantum computing for cybersecurity?\"`\n    - With more researchers and deeper exploration: `npc alicanto \"How might climate change impact global food security?\" --num-npcs 8 --depth 5`\n    - Control exploration vs. exploitation balance: `npc alicanto \"What ethical considerations should guide AI development?\" --exploration 0.5`\n    - Different output formats: `npc alicanto \"What is the future of remote work?\" --format report`\n\n- **`pti`**: A reasoning REPL loop with explicit checks to request inputs from users following thinking traces.\n    - Usage: `pti`\n\n- **`spool`**: A simple agentic","faq":null,"created_at":"2024-09-27T07:18:20+00:00","updated_at":"2025-07-07T10:35:22+00:00","source_url":"https://model-context-protocol.com/servers/npcpy","related_articles":[]}