{"id":27724397,"url":"https://github.com/cagostino/npcpy","last_synced_at":"2025-04-27T16:02:09.502Z","repository":{"id":257806495,"uuid":"863930645","full_name":"cagostino/npcpy","owner":"cagostino","description":"The AI toolkit for the AI developer","archived":false,"fork":false,"pushed_at":"2025-04-24T20:42:09.000Z","size":10442,"stargazers_count":556,"open_issues_count":6,"forks_count":30,"subscribers_count":14,"default_branch":"main","last_synced_at":"2025-04-24T21:42:39.417Z","etag":null,"topics":["agents","ai","anthropic","deepseek","gemini","llm","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/cagostino.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},"funding":{"github":"cagostino","buy_me_a_coffee":"npcworldwide"}},"created_at":"2024-09-27T07:18:20.000Z","updated_at":"2025-04-24T19:20:50.000Z","dependencies_parsed_at":null,"dependency_job_id":"1991f9d9-ba6c-4962-b3c7-0da0b1fb3df8","html_url":"https://github.com/cagostino/npcpy","commit_stats":null,"previous_names":["cagostino/npcsh","cagostino/npcpy"],"tags_count":114,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cagostino%2Fnpcpy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cagostino%2Fnpcpy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cagostino%2Fnpcpy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cagostino%2Fnpcpy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cagostino","download_url":"https://codeload.github.com/cagostino/npcpy/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251166189,"owners_count":21546172,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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","anthropic","deepseek","gemini","llm","ollama","perplexity","python","sql","yaml"],"created_at":"2025-04-27T16:02:08.172Z","updated_at":"2025-04-27T16:02:09.491Z","avatar_url":"https://github.com/cagostino.png","language":"Python","funding_links":["https://github.com/sponsors/cagostino","https://buymeacoffee.com/npcworldwide"],"categories":["Python"],"sub_categories":[],"readme":"\n\n# NPC Toolkit\n\n\n- `npcpy` is a python framework designed to easily integrate Large Language Models and AI agents.\n- `npcpy` works with local and enterprise LLM providers through its LiteLLM integration, allowing users to run inference from Ollama, LMStudio, OpenAI, Anthropic, Gemini, and Deepseek, making it a versatile tool for both simple commands and sophisticated AI-driven tasks. \n- In `npcpy`, all agentic capabilities are built and tested using small local models (like `llama3.2`) to ensure it can function reliably even at the edge of computing.\n- In addition to its python library capabilities, `npcpy` provides users with powerful command-line tools and macros for quick and easy access to LLMs. These programs comprise the NPC `shell` and such functionalities are available for use in multiple ways: through the `npc` bash cli, directly through the `npcsh` shell or through their individual paths. \n- The NPC Shell `npcsh` provides a drop-in replacement for one's bash shell with natural language processing capabilities and a suite of built-in tools (macros) for tasks like voice control, image generation, and web searching. Through it's simple REPL system, one can interact with agents and orchestrate agent teams.\n- With the `npc` CLI, users can use the same tools and macros of the NPC shell through a CLI and provides a quick and simple way to RESTfully serve an NPC Team to receive HTTP requests.\n- The NPC Toolkit integrates with local and enterprise LLM providers through its LiteLLM integration, allowing users to run inference from Ollama, LMStudio, OpenAI, Anthropic, Gemini, and Deepseek, making it a versatile tool for both simple commands and sophisticated AI-driven tasks. All agentic capabilities are built and tested using small local models (like `llama3.2`) to ensure the agentic capabilities function even at the edge of computing.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/cagostino/npcsh/main/npcpy.png\" alt=\"npcpy logo of a solarpunk sign\"\u003e\n\u003c/p\u003e\n\n\n\nRead the docs at [npcpy.readthedocs.io](https://npcsh.readthedocs.io/en/latest/)\n\nThere is a graphical user interface that makes use of the NPC Toolkit through the NPC Studio. See the open source code for NPC Studio [here](https://github.com/). Download the executables (soon) at [our website](https://www.npcworldwi.de/npc-studio).\n\nInterested to stay in the loop and to hear the latest and greatest about `npcpy`, `npcsh`, and NPC Studio? Be sure to sign up for the [newsletter](https://forms.gle/n1NzQmwjsV4xv1B2A)!\n\n\n\n\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\n## TLDR Cheat Sheet for NPC shell and cli\nThe NPC shell and cli let users iterate and experiiment with AI in a natural way. Below is a cheat sheet that shows how to use the NPC Toolkit's macro commands in both the shell and the CLI. For the `npcsh` commands to work, one must activate `npcsh` by typing it in a shell.\n\n| Task | npc CLI | npcsh |\n|----------|----------|----------|\n| Ask a generic question | npc 'prompt' | 'prompt' |\n| Compile an NPC | npc compile /path/to/npc.npc | /compile /path/to/npc.npc |\n| Computer use | npc plonk -n 'npc_name' -sp 'task for plonk to carry out '| /plonk -n 'npc_name' -sp 'task for plonk to carry out ' |\n| Conjure an NPC team from context and templates | npc init -t 'template1, template2' -ctx 'context'   | /conjure  -t 'template1, 'template2' -ctx 'context'  |\n| Enter a chat with an NPC (NPC needs to be compiled first) | npc chat -n npc_name | /spool npc=\u003cnpc_name\u003e |\n| Generate image    | npc vixynt 'prompt'  | /vixynt prompt   |\n| Get a sample LLM response  | npc sample 'prompt'   | /sample prompt for llm  |\n| Search the web | npc search -q \"cal golden bears football schedule\" -sp perplexity | /search -p perplexity 'cal bears football schedule' |\n| Serve an NPC team | npc serve --port 5337 --cors='http://localhost:5137/' | /serve --port 5337 --cors='http://localhost:5137/' |\n| Screenshot analysis  | npc ots |  /ots  |\n| Voice Chat    | npc whisper -n 'npc_name'   | /whisper   |\n\n\nWhen beginning, `npcsh` initializes a set of agents that you can use and tweak as you go. Our mascot agent is sibiji the spider and he will help you weave your agent web! \n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/cagostino/npcsh/main/npcpy/npcsh.png\" alt=\"npcsh logo with sibiji the spider\"\u003e\n\u003c/p\u003e\n\n\n\n## Python Examples\nIntegrate `npcpy` into your Python projects for additional flexibility. Below are a few examples of how to use the library programmatically.\n\n### Example 1: using npcpy's get_llm_response and get_stream\n\n```python\nfrom npcpy.llm_funcs import get_llm_response\n\n# ollama's llama3.2\nresponse = get_llm_response(\"What is the capital of France? Respond with a json object containing 'capital' as the key and the capital as the value.\",\n                            model='llama3.2',\n                            provider='ollama',\n                            format='json')\nprint(response)\n# assistant's response is contained in the 'response' key for easier access\nassistant_response = response['response']\nprint(assistant_response)\n# access messages too\nmessages = response['messages']\nprint(messages)\n\n\n#openai's gpt-4o-mini\nfrom npcpy.llm_funcs import get_llm_response\n\nresponse = get_llm_response(\"What is the capital of France? Respond with a json object containing 'capital' as the key and the capital as the value.\",\n                            model='gpt-4o-mini',\n                            provider='openai',\n                            format='json')\nprint(response)\n# anthropic's claude haikue 3.5 latest\nfrom npcpy.llm_funcs import get_llm_response\n\nresponse = get_llm_response(\"What is the capital of France? Respond with a json object containing 'capital' as the key and the capital as the value.\",\n                            model='claude-3-5-haiku-latest',\n                            provider='anthropic',\n                            format='json')\n\n\n\n# alternatively, if you have NPCSH_CHAT_MODEL / NPCSH_CHAT_PROVIDER set in your ~/.npcshrc, it will use those values\nresponse = get_llm_response(\"What is the capital of France? Respond with a json object containing 'capital' as the key and the capital as the value.\",\n                            format='json')\n\n\n# with stream\n# alternatively, if you have NPCSH_CHAT_MODEL / NPCSH_CHAT_PROVIDER set in your ~/.npcshrc, it will use those values\nresponse = get_llm_response(\"whats going on tonight?\",\n                            model='gpt-4o-mini',\n                            provider='openai',\n                            stream=True)\n\nfor chunk in response['response']:\n    print(chunk)\n```\n\n### Example 2: Building a flow with check_llm_command\n\n```python\n#first let's demonstrate the capabilities of npcsh's check_llm_command\nfrom npcpy.llm_funcs import check_llm_command\n\ncommand = 'can you write a description of the idea of semantic degeneracy?'\n\nresponse = check_llm_command(command,\n                             model='gpt-4o-mini',\n                             provider='openai')\n\n\n\n# now to make the most of check_llm_command, let's add an NPC with a generic code execution tool\n\n\nfrom npcpy.npc_compiler import NPC, Tool\nfrom npcpy.llm_funcs import check_llm_command\n\ncode_execution_tool = Tool(\n    {\n        \"tool_name\": \"execute_python\",\n        \"description\": \"\"\"Executes a code block in python.\n                Final output from script MUST be stored in a variable called `output`.\n                          \"\"\",\n        \"inputs\": [\"script\"],\n        \"steps\": [\n            {\n                \"engine\": \" python\",\n                \"code\": \"\"\"{{ script }}\"\"\",\n            }\n        ],\n    }\n)\n\n\ncommand = \"\"\"can you write a description of the idea of semantic degeneracy and save it to a file?\n             After, can you take that and make various versions of it from the points of\n             views of different sub-disciplines of natural lanaguage processing?\n             Finally produce a synthesis of the resultant various versions and save it.\"\n            \"\"\"\nnpc = NPC(\n    name=\"NLP_Master\",\n    primary_directive=\"Provide astute anlayses on topics related to NLP. Carry out relevant tasks for users to aid them in their NLP-based analyses\",\n    model=\"gpt-4o-mini\",\n    provider=\"openai\",\n    tools=[code_execution_tool],\n)\nresponse = check_llm_command(\n    command, model=\"gpt-4o-mini\", provider=\"openai\", npc=npc, stream=False\n)\n\n\n# or by attaching an NPC Team\nfrom npcpy.npc_compiler import NPC\n\nresponse = check_llm_command(command,\n                             model='gpt-4o-mini',\n                              provider='openai',)\n```\n\n\n\n### Example 3: Creating and Using an NPC\nThis example shows how to create and initialize an NPC and use it to answer a question.\n```python\nimport sqlite3\nfrom npcpy.npc_compiler import NPC\n\n# Set up database connection\ndb_path = '~/npcsh_history.db'\nconn = sqlite3.connect(db_path)\n\n# Load NPC from a file\nnpc = NPC(\n          name='Simon Bolivar',\n          db_conn=conn,\n          primary_directive='Liberate South America from the Spanish Royalists.',\n          model='gpt-4o-mini',\n          provider='openai',\n          )\n\nresponse = npc.get_llm_response(\"What is the most important territory to retain in the Andes mountains?\")\nprint(response['response'])\n```\n```bash\n'The most important territory to retain in the Andes mountains for the cause of liberation in South America would be the region of Quito in present-day Ecuador. This area is strategically significant due to its location and access to key trade routes. It also acts as a vital link between the northern and southern parts of the continent, influencing both military movements and the morale of the independence struggle. Retaining control over Quito would bolster efforts to unite various factions in the fight against Spanish colonial rule across the Andean states.'\n```\n### Example 4: Using an NPC to Analyze Data\nThis example shows how to use an NPC to perform data analysis on a DataFrame using LLM commands.\n```python\nfrom npcpy.npc_compiler import NPC\nimport sqlite3\nimport os\n# Set up database connection\ndb_path = '~/npcsh_history.db'\nconn = sqlite3.connect(os.path.expanduser(db_path))\n\n# make a table to put into npcsh_history.db or change this example to use an existing table in a database you have\nimport pandas as pd\ndata = {\n        'customer_feedback': ['The product is great!', 'The service was terrible.', 'I love the new feature.'],\n        'customer_id': [1, 2, 3],\n        'customer_rating': [5, 1, 3],\n        'timestamp': ['2022-01-01', '2022-01-02', '2022-01-03']\n        }\n\n\ndf = pd.DataFrame(data)\ndf.to_sql('customer_feedback', conn, if_exists='replace', index=False)\n\n\nnpc = NPC(\n          name='Felix',\n          db_conn=conn,\n          primary_directive='Analyze customer feedback for sentiment.',\n          model='gpt-4o-mini',\n          provider='openai',\n          )\nresponse = npc.analyze_db_data('Provide a detailed report on the data contained in the `customer_feedback` table?')\n\n\n```\n\n\n### Example 5: Creating and Using a Tool\nYou can define a tool and execute it from within your Python script.\nHere we'll create a tool that will take in a pdf file, extract the text, and then answer a user request about the text.\n\n```python\nfrom npcpy.npc_compiler import Tool, NPC\nimport sqlite3\nimport os\n\nfrom jinja2 import Environment, FileSystemLoader\n\n# Create a proper Jinja environment\njinja_env = Environment(loader=FileSystemLoader('.'))\n\n\ntool_data = {\n    \"tool_name\": \"pdf_analyzer\",\n    \"inputs\": [\"request\", \"file\"],\n    \"steps\": [{  # Make this a list with one dict inside\n        \"engine\": \"python\",\n        \"code\": \"\"\"\ntry:\n    import fitz  # PyMuPDF\n\n    shared_context = {}\n    shared_context['inputs'] = '{{request}}'\n\n    pdf_path = '{{file}}'\n\n\n\n    # Open the PDF\n    doc = fitz.open(pdf_path)\n    text = \"\"\n\n    # Extract text from each page\n    for page_num in range(len(doc)):\n        page = doc[page_num]\n        text += page.get_text()\n\n    # Close the document\n    doc.close()\n\n    print(f\"Extracted text length: {len(text)}\")\n    if len(text) \u003e 100:\n        print(f\"First 100 characters: {text[:100]}...\")\n\n    shared_context['extracted_text'] = text\n    print(\"Text extraction completed successfully\")\n\nexcept Exception as e:\n    error_msg = f\"Error processing PDF: {str(e)}\"\n    print(error_msg)\n    shared_context['extracted_text'] = f\"Error: {error_msg}\"\n\"\"\"\n    },\n     {\n        \"engine\": \"natural\",\n        \"code\": \"\"\"\n{% if shared_context and shared_context.extracted_text %}\n{% if shared_context.extracted_text.startswith('Error:') %}\n{{ shared_context.extracted_text }}\n{% else %}\nHere is the text extracted from the PDF:\n\n{{ shared_context.extracted_text }}\n\nPlease provide a response to user request: {{ request }} using the information extracted above.\n{% endif %}\n{% else %}\nError: No text was extracted from the PDF.\n{% endif %}\n\"\"\"\n    },]\n    }\n\n# Instantiate the tool\ntool = Tool(tool_data)\n\n# Create an NPC instance\nnpc = NPC(\n    name='starlana',\n    primary_directive='Analyze text from Astrophysics papers with a keen attention to theoretical machinations and mechanisms.',\n    model = 'llama3.2',\n    provider='ollama',\n    db_conn=sqlite3.connect(os.path.expanduser('~/npcsh_database.db'))\n)\n\n# Define input values dictionary\ninput_values = {\n    \"request\": \"what is the point of the yuan and narayanan work?\",\n    \"file\": os.path.abspath(\"test_data/yuan2004.pdf\")\n}\n\nprint(f\"Attempting to read file: {input_values['file']}\")\nprint(f\"File exists: {os.path.exists(input_values['file'])}\")\n\n# Execute the tool\noutput = tool.execute(input_values, npc.tools_dict, jinja_env, 'Sample Command',model=npc.model, provider=npc.provider,  npc=npc)\n\nprint('Tool Output:', output)\n```\n\n### Example 6: Orchestrating a team\n\n\n\n```python\nimport pandas as pd\nimport numpy as np\nimport os\nfrom npcpy.npc_compiler import NPC, Team, Tool\n\n\n# Create test data and save to CSV\ndef create_test_data(filepath=\"sales_data.csv\"):\n    sales_data = pd.DataFrame(\n        {\n            \"date\": pd.date_range(start=\"2024-01-01\", periods=90),\n            \"revenue\": np.random.normal(10000, 2000, 90),\n            \"customer_count\": np.random.poisson(100, 90),\n            \"avg_ticket\": np.random.normal(100, 20, 90),\n            \"region\": np.random.choice([\"North\", \"South\", \"East\", \"West\"], 90),\n            \"channel\": np.random.choice([\"Online\", \"Store\", \"Mobile\"], 90),\n        }\n    )\n\n    # Add patterns to make data more realistic\n    sales_data[\"revenue\"] *= 1 + 0.3 * np.sin(\n        np.pi * np.arange(90) / 30\n    )  # Seasonal pattern\n    sales_data.loc[sales_data[\"channel\"] == \"Mobile\", \"revenue\"] *= 1.1  # Mobile growth\n    sales_data.loc[\n        sales_data[\"channel\"] == \"Online\", \"customer_count\"\n    ] *= 1.2  # Online customer growth\n\n    sales_data.to_csv(filepath, index=False)\n    return filepath, sales_data\n\n\ncode_execution_tool = Tool(\n    {\n        \"tool_name\": \"execute_code\",\n        \"description\": \"\"\"Executes a Python code block with access to pandas,\n                          numpy, and matplotlib.\n                          Results should be stored in the 'results' dict to be returned.\n                          The only input should be a single code block with \\n characters included.\n                          The code block must use only the  libraries or methods contained withen the\n                            pandas, numpy, and matplotlib libraries or using builtin methods.\n                          do not include any json formatting or markdown formatting.\n\n                          When generating your script, the final output must be encoded in a variable\n                          named \"output\". e.g.\n\n                          output  = some_analysis_function(inputs, derived_data_from_inputs)\n                            Adapt accordingly based on the scope of the analysis\n\n                          \"\"\",\n        \"inputs\": [\"script\"],\n        \"steps\": [\n            {\n                \"engine\": \"python\",\n                \"code\": \"\"\"{{script}}\"\"\",\n            }\n        ],\n    }\n)\n\n# Analytics team definition\nanalytics_team = [\n    {\n        \"name\": \"analyst\",\n        \"primary_directive\": \"You analyze sales performance data, focusing on revenue trends, customer behavior metrics, and market indicators. Your expertise is in extracting actionable insights from complex datasets.\",\n        \"model\": \"gpt-4o-mini\",\n        \"provider\": \"openai\",\n        \"tools\": [code_execution_tool],  # Only the code execution tool\n    },\n    {\n        \"name\": \"researcher\",\n        \"primary_directive\": \"You specialize in causal analysis and experimental design. Given data insights, you determine what factors drive observed patterns and design tests to validate hypotheses.\",\n        \"model\": \"gpt-4o-mini\",\n        \"provider\": \"openai\",\n        \"tools\": [code_execution_tool],  # Only the code execution tool\n    },\n    {\n        \"name\": \"engineer\",\n        \"primary_directive\": \"You implement data pipelines and optimize data processing. When given analysis requirements, you create efficient workflows to automate insights generation.\",\n        \"model\": \"gpt-4o-mini\",\n        \"provider\": \"openai\",\n        \"tools\": [code_execution_tool],  # Only the code execution tool\n    },\n]\n\n\ndef create_analytics_team():\n    # Initialize NPCs with just the code execution tool\n    npcs = []\n    for npc_data in analytics_team:\n        npc = NPC(\n            name=npc_data[\"name\"],\n            primary_directive=npc_data[\"primary_directive\"],\n            model=npc_data[\"model\"],\n            provider=npc_data[\"provider\"],\n            tools=[code_execution_tool],  # Only code execution tool\n        )\n        npcs.append(npc)\n\n    # Create coordinator with just code execution tool\n    coordinator = NPC(\n        name=\"coordinator\",\n        primary_directive=\"You coordinate the analytics team, ensuring each specialist contributes their expertise effectively. You synthesize insights and manage the workflow.\",\n        model=\"gpt-4o-mini\",\n        provider=\"openai\",\n        tools=[code_execution_tool],  # Only code execution tool\n    )\n\n    # Create team\n    team = Team(npcs=npcs, foreman=coordinator)\n    return team\n\n\ndef main():\n    # Create and save test data\n    data_path, sales_data = create_test_data()\n\n    # Initialize team\n    team = create_analytics_team()\n\n    # Run analysis - updated prompt to reflect code execution approach\n    results = team.orchestrate(\n        f\"\"\"\n    Analyze the sales data at {data_path} to:\n    1. Identify key performance drivers\n    2. Determine if mobile channel growth is significant\n    3. Recommend tests to validate growth hypotheses\n\n    Here is a header for the data file at {data_path}:\n    {sales_data.head()}\n\n    When working with dates, ensure that date columns are converted from raw strings. e.g. use the pd.to_datetime function.\n\n\n    When working with potentially messy data, handle null values by using nan versions of numpy functions or\n    by filtering them with a mask .\n\n    Use Python code execution to perform the analysis - load the data and perform statistical analysis directly.\n    \"\"\"\n    )\n\n    print(results)\n\n    # Cleanup\n    os.remove(data_path)\n\n\nif __name__ == \"__main__\":\n    main()\n\n```\n\n\n\n## Installation\n`npcpy` is available on PyPI and can be installed using pip. Before installing, make sure you have the necessary dependencies installed on your system. Below are the instructions for installing such dependencies on Linux, Mac, and Windows. If you find any other dependencies that are needed, please let us know so we can update the installation instructions to be more accommodating.\n\n### Linux install\n```bash\n\n# for audio primarily\nsudo apt-get install espeak\nsudo apt-get install portaudio19-dev python3-pyaudio\nsudo apt-get install alsa-base alsa-utils\nsudo apt-get install libcairo2-dev\nsudo apt-get install libgirepository1.0-dev\nsudo apt-get install ffmpeg\n\n# for triggers\nsudo apt install inotify-tools\n\n\n#And if you don't have ollama installed, use this:\ncurl -fsSL https://ollama.com/install.sh | sh\n\nollama pull llama3.2\nollama pull llava:7b\nollama pull nomic-embed-text\npip install npcpy\n# if you want to install with the API libraries\npip install npcpy[lite]\n# if you want the full local package set up (ollama, diffusers, transformers, cuda etc.)\npip install npcpy[local]\n# if you want to use tts/stt\npip install npcpy[whisper]\n\n# if you want everything:\npip install npcpy[all]\n\n\n\n\n### Mac install\n```bash\n#mainly for audio\nbrew install portaudio\nbrew install ffmpeg\nbrew install pygobject3\n\n# for triggers\nbrew install ...\n\n\nbrew install ollama\nbrew services start ollama\nollama pull llama3.2\nollama pull llava:7b\nollama pull nomic-embed-text\npip install npcsh\n# if you want to install with the API libraries\npip install npcpy[lite]\n# if you want the full local package set up (ollama, diffusers, transformers, cuda etc.)\npip install npcpy[local]\n# if you want to use tts/stt\npip install npcpy[whisper]\n\n# if you want everything:\npip install npcpy[all]\n\n```\n### Windows Install\n\nDownload and install ollama exe.\n\nThen, in a powershell. Download and install ffmpeg.\n\n```\nollama pull llama3.2\nollama pull llava:7b\nollama pull nomic-embed-text\npip install npcsh\n# if you want to install with the API libraries\npip install npcsh[lite]\n# if you want the full local package set up (ollama, diffusers, transformers, cuda etc.)\npip install npcpy[local]\n# if you want to use tts/stt\npip install npcpy[yap]\n\n# if you want everything:\npip install npcpy[all]\n\n```\nAs of now, npcsh appears to work well with some of the core functionalities like /ots and /whisper.\n\n\n### Fedora Install (under construction)\n\npython3-dev (fixes hnswlib issues with chroma db)\nxhost +  (pyautogui)\npython-tkinter (pyautogui)\n\n## Startup Configuration and Project Structure\nAfter it has been pip installed, `npcsh` can be used as a command line tool. Start it by typing:\n```bash\nnpcsh\n```\nWhen initialized, `npcsh` will generate a .npcshrc file in your home directory that stores your npcsh settings.\nHere is an example of what the .npcshrc file might look like after this has been run.\n```bash\n# NPCSH Configuration File\nexport NPCSH_INITIALIZED=1\nexport NPCSH_CHAT_PROVIDER='ollama'\nexport NPCSH_CHAT_MODEL='llama3.2'\nexport NPCSH_DB_PATH='~/npcsh_history.db'\n```\n`npcsh` also comes with a set of tools and NPCs that are used in processing. It will generate a folder at ~/.npcsh/ that contains the tools and NPCs that are used in the shell and these will be used in the absence of other project-specific ones. Additionally, `npcsh` records interactions and compiled information about npcs within a local SQLite database at the path specified in the .npcshrc file. This will default to ~/npcsh_history.db if not specified. When the data mode is used to load or analyze data in CSVs or PDFs, these data will be stored in the same database for future reference.\n\nThe installer will automatically add this file to your shell config, but if it does not do so successfully for whatever reason you can add the following to your .bashrc or .zshrc:\n\n```bash\n# Source NPCSH configuration\nif [ -f ~/.npcshrc ]; then\n    . ~/.npcshrc\nfi\n```\n\nWe support inference via all providers supported by litellm. For openai-compatible providers that are not explicitly named in litellm, use simply `openai-like` as the provider. The default provider must be one of `['openai','anthropic','ollama', 'gemini', 'deepseek', 'openai-like']` and the model must be one available from those providers.\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. Here is an example of what an `.env` file might look like:\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\n\n Individual npcs can also be set to use different models and providers by setting the `model` and `provider` keys in the npc files.\n Once initialized and set up, you will find the following in your ~/.npcsh directory:\n```bash\n~/.npcsh/\n├── npc_team/           # Global NPCs\n│   ├── tools/          # Global tools\n│   └── assembly_lines/ # Workflow pipelines\n\n```\nFor cases where you wish to set up a project specific set of NPCs, tools, and assembly lines, add a `npc_team` directory to your project and `npcsh` should be able to pick up on its presence, like so:\n```bash\n./npc_team/            # Project-specific NPCs\n├── tools/             # Project tools #example tool next\n│   └── example.tool\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\n\n```\n\n## IMPORTANT: migrations and deprecations and major changes\n\n### v0.3.33\n-In v0.3.33, the NPCCompiler object was phased out and the global/project dichotomy was removed. \n-the primary python package entrypoint was renamed from npcsh to npcpy\n-npcsh is still automatically installed and available, but we will have a better separation of responsibilities in the NPC framework when the shell handles these rather than integrating it across the library.\n-context files are being introduced.\n\n\n### v0.3.4\n-In v0.3.4, the structure for tools was adjusted. If you have made custom tools please refer to the structure within npc_compiler to ensure that they are in the correct format. Otherwise, do the following\n```bash\nrm ~/.npcsh/npc_team/tools/*.tool\n```\nand then\n```bash\nnpcsh\n```\nand the updated tools will be copied over into the correct location.\n\n### v0.3.5\n-Version 0.3.5 included a complete overhaul and refactoring of the llm_funcs module. This was done to make it not as horribly long and to make it easier to add new models and providers\n\n\n-in version 0.3.5, a change was introduced to the database schema for messages to add npcs, models, providers, and associated attachments to data. If you have used `npcsh` before this version, you will need to run this migration script to update your database schema:   [migrate_conversation_history_v0.3.5.py](https://github.com/cagostino/npcsh/blob/cfb9dc226e227b3e888f3abab53585693e77f43d/npcsh/migrations/migrate_conversation_history_%3Cv0.3.4-%3Ev0.3.5.py)\n\n-additionally, NPCSH_MODEL and NPCSH_PROVIDER have been renamed to NPCSH_CHAT_MODEL and NPCSH_CHAT_PROVIDER\nto provide a more consistent naming scheme now that we have additionally introduced `NPCSH_VISION_MODEL` and `NPCSH_VISION_PROVIDER`, `NPCSH_EMBEDDING_MODEL`, `NPCSH_EMBEDDING_PROVIDER`, `NPCSH_REASONING_MODEL`, `NPCSH_REASONING_PROVIDER`, `NPCSH_IMAGE_GEN_MODEL`, and `NPCSH_IMAGE_GEN_PROVIDER`.\n- In addition, we have added NPCSH_API_URL to better accommodate openai-like apis that require a specific url to be set as well as `NPCSH_STREAM_OUTPUT` to indicate whether or not to use streaming in one's responses. It will be set to 0 (false) by default as it has only been tested  and verified for a small subset of the models and providers we have available (openai, anthropic, and ollama). If you try it and run into issues, please post them here so we can correct them as soon as possible !\n\n\n\n## Contributing\nContributions are welcome! Please submit issues and pull requests on the GitHub repository.\n\n## Support\nIf you appreciate the work here, [consider supporting NPC Worldwide](https://buymeacoffee.com/npcworldwide). If you'd like to explore how to use `npcsh` to help your business, please reach out to info@npcworldwi.de .\n\n\n## NPC Studio\nComing soon! NPC Studio will be a desktop application for managing chats and agents on your own machine.\nBe sure to sign up for the [npcsh newsletter](https://forms.gle/n1NzQmwjsV4xv1B2A) to hear updates!\n\n## License\nThis project is licensed under the MIT License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcagostino%2Fnpcpy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcagostino%2Fnpcpy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcagostino%2Fnpcpy/lists"}