PyPI - npcsh - Versions diffs - 1.0.17__tar.gz → 1.0.19__tar.gz - Mend

npcsh 1.0.17tar.gz → 1.0.19tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (26) hide show

{npcsh-1.0.17 → npcsh-1.0.19}/PKG-INFO RENAMED Viewed

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: npcsh
-Version: 1.0.17
+Version: 1.0.19
 Summary: npcsh is a command-line toolkit for using AI agents in novel ways.
 Home-page: https://github.com/NPC-Worldwide/npcsh
 Author: Christopher Agostino
@@ -43,6 +43,7 @@ Requires-Dist: redis
 Requires-Dist: psycopg2-binary
 Requires-Dist: flask_sse
 Requires-Dist: wikipedia
+Requires-Dist: mcp
 Provides-Extra: lite
 Requires-Dist: anthropic; extra == "lite"
 Requires-Dist: openai; extra == "lite"
@@ -65,8 +66,6 @@ Requires-Dist: playsound==1.2.2; extra == "yap"
 Requires-Dist: pygame; extra == "yap"
 Requires-Dist: faster_whisper; extra == "yap"
 Requires-Dist: pyttsx3; extra == "yap"
-Provides-Extra: mcp
-Requires-Dist: mcp; extra == "mcp"
 Provides-Extra: all
 Requires-Dist: anthropic; extra == "all"
 Requires-Dist: openai; extra == "all"
@@ -87,7 +86,6 @@ Requires-Dist: playsound==1.2.2; extra == "all"
 Requires-Dist: pygame; extra == "all"
 Requires-Dist: faster_whisper; extra == "all"
 Requires-Dist: pyttsx3; extra == "all"
-Requires-Dist: mcp; extra == "all"
 Dynamic: author
 Dynamic: author-email
 Dynamic: classifier
@@ -107,21 +105,25 @@ Dynamic: summary
 # NPC Shell
-The NPC shell is a suite of executable command-line programs that allow users to easily interact with NPCs and LLMs through a command line shell.
-Programs within the NPC shell use the properties defined in `~/.npcshrc`, which is generated upon installation and running of `npcsh` for the first time.
+The NPC shell is the toolkit for tomorrow, providing a suite of programs to make use of multi-modal LLMs and agents in novel interactive modes. `npcsh` is a command-line program, and so can be used wherever you work. `npcsh` is developed to work relibly with small models and performs excellently with the state-of-the-art models from major model providers.
 To get started:
-```
+```bash
+# for users who want to mainly use models through APIs (e.g. , gemini, grok, deepseek, anthropic, openai, mistral, , any others provided by litellm ):
+pip install 'npcsh[lite]'
+# for users who want to use local models (these install diffusers/transformers/torch stack so it is big.):
 pip install 'npcsh[local]'
+# for users who want to use the voice mode `yap`, see also the OS-specific installation instructions for installing needed system audio  libraries
+pip install 'npcsh[yap]'
 ```
-Once installed, the following CLI tools will be available: `npcsh`, `guac`, `npc` cli, `yap` `pti`, `wander`, and `spool`.
-# npcsh
-- An AI-powered shell that parses bash, natural language, and special macro calls, `npcsh` processes your input accordingly, agentically, and automatically.
+Once installed: run
+```bash
+npcsh
+```
+and you will enter the NPC shell. Additionally, the pip installation includes making the following CLI tools available in bash: `corca`, `guac`, `npc` cli, `pti`, `spool`, `wander`, and`yap`.
+# Usage
   - Get help with a task:
       ```bash
       npcsh:🤖sibiji:gemini-2.5-flash>can you help me identify what process is listening on port 5337?
@@ -139,18 +141,7 @@ Once installed, the following CLI tools will be available: `npcsh`, `guac`, `npc
     ```bash
     npcsh> has there ever been a better pasta shape than bucatini?
     ```
-    ```
-    Ultimately, the "best" pasta shape depends on personal preference and the dish being prepared. Bucatini shines in specific contexts, but pasta lovers often appreciate a diverse range of shapes for their unique qualities and compatibilities with various sauces and ingredients. Each shape has its place in the culinary world, and trying different types can enhance the overall dining experience.
-    ```
-    ```
-    .Loaded .env file...
-    Initializing database schema...
-    Database schema initialization complete.
-    Processing prompt: 'has there ever been a better pasta shape than bucatini?' with NPC: 'sibiji'...
-    • Action chosen: answer_question
-    • Explanation given: The question is a general opinion-based inquiry about pasta shapes and can be answered without external data or jinx invocation.
-    ...............................................................................
+    ```
     Bucatini is certainly a favorite for many due to its unique hollow center, which holds sauces beautifully. Whether it's "better" is subjective and depends on the dish and personal
     preference. Shapes like orecchiette, rigatoni, or trofie excel in different recipes. Bucatini stands out for its versatility and texture, making it a top contender among pasta shapes!
     ```
@@ -193,38 +184,67 @@ Once installed, the following CLI tools will be available: `npcsh`, `guac`, `npc
     ```bash
     /ots
     ```
+  - **Use an mcp server**: make use of NPCs with MCP servers.
+    ```bash
+    /corca --mcp-server-path /path.to.server.py
+    ```
+# NPC Data Layer
+The core of npcsh's capabilities is powered by the NPC Data Layer. Upon initialization, a user will be prompted to make a team in the current directory or to use a global team stored in `~/.npcsh/` which houses the NPC team with its jinxs, models, contexts, assembly lines. By implementing these components as simple data structures, users can focus on tweaking the relevant parts of their multi-agent systems.
+## Creating Custom Components
+Users can extend NPC capabilities through simple YAML files:
+- **NPCs** (.npc): are defined with a name, primary directive, and optional model specifications
+- **Jinxs** (.jinx): specify function-like capabilities with preprocessing, execution, and postprocessing steps
+- **Context** (.ctx): Specify contextual information, team preferences, MCP server paths, database connections, and other environment variables that are loaded for the team. Teams are specified by their path and the team name in the `<team>.ctx` file. Teams organize collections of NPCs with shared context and specify a coordinator within the team context
+The NPC Shell system integrates the capabilities of `npcpy` to maintain conversation history, track command execution, and provide intelligent autocomplete through an extensible command routing system. State is preserved between sessions, allowing for continuous knowledge building over time.
+This architecture enables complex AI workflows while maintaining a simple, declarative syntax that abstracts away implementation complexity. By organizing AI capabilities as composable data structures rather than code, npcsh creates a more accessible and adaptable framework for AI automation.
 # Macros
 -  activated by invoking `/<command> ...` in `npcsh`, macros can be called in bash or through the `npc` CLI. In our examples, we provide both `npcsh` calls as well as bash calls with the `npc` cli where relevant. For converting any `/<command>` in `npcsh` to a bash version, replace the `/` with `npc ` and the macro command will be invoked as a positional argument. Some, like breathe, flush,
-    - `/alicanto` - Conduct deep research with multiple perspectives, identifying gold insights and cliff warnings
-    - `/brainblast` - Execute an advanced chunked search on command history
-    - `/breathe` - Condense context on a regular cadence
-    - `/compile` - Compile NPC profiles
-    - `/corca` - Enter the Corca MCP-powered agentic shell. Usage: /corca [--mcp-server-path path]
-    - `/flush` - Flush the last N messages
-    - `/guac` - Enter guac mode
-    - `/help` - Show help for commands, NPCs, or Jinxs. Usage: /help
-    - `/init` - Initialize NPC project
-    - `/jinxs` - Show available jinxs for the current NPC/Team
-    - `/npc-studio` - Start npc studio
-    - `/ots` - Take screenshot and analyze with vision model
-    - `/plan` - Execute a plan command
-    - `/plonk` - Use vision model to interact with GUI. Usage: /plonk <task description>
-    - `/pti` - Use pardon-the-interruption mode to interact with reasoning model LLM
-    - `/rag` - Execute a RAG command using ChromaDB embeddings with optional file input (-f/--file)
-    - `/roll` - generate a video with video generation model
-    - `/sample` - Send a prompt directly to the LLM
-    - `/search` - Execute a web search command
-    - `/serve` - Serve an NPC Team server.
-    - `/set` - Set configuration values
-    - `/sleep` - Evolve knowledge graph with options for dreaming.
-    - `/spool` - Enter interactive chat (spool) mode with an npc with fresh context or files for rag
-    - `/trigger` - Execute a trigger command
-    - `/vixynt` - Generate and edit images from text descriptions using local models, openai, gemini
-    - `/wander` - A method for LLMs to think on a problem by switching between states of high temperature and low temperature
-    - `/yap` - Enter voice chat (yap) mode
+    - `/alicanto` - Conduct deep research with multiple perspectives, identifying gold insights and cliff warnings. Usage: `/alicanto 'query to be researched' --num-npcs <int> --depth <int>`
+    - `/brainblast` - Execute an advanced chunked search on command history. Usage:     `/brainblast 'query'  --top_k 10`
+    - `/breathe` - Condense context on a regular cadence. Usage: `/breathe -p <provider: NPCSH_CHAT_PROVIDER> -m <model: NPCSH_CHAT_MODEL>`
+    - `/compile` - Compile NPC profiles. Usage: `/compile <path_to_npc> `
+    - `/corca` - Enter the Corca MCP-powered agentic shell. Usage: `/corca [--mcp-server-path path]`
+    - `/flush` - Flush the last N messages. Usage: `/flush N=10`
+    - `/guac` - Enter guac mode. Usage: `/guac`
+    - `/help` - Show help for commands, NPCs, or Jinxs. Usage: `/help`
+    - `/init` - Initialize NPC project. Usage: `/init`
+    - `/jinxs` - Show available jinxs for the current NPC/Team. Usage: `/jinxs`
+    - `/<jinx_name>` - Run a jinx with specified command line arguments. `/<jinx_name> jinx_arg1 jinx_arg2`
+    - `/npc-studio` - Start npc studio. Pulls NPC Studio github to `~/.npcsh/npc-studio` and launches it in development mode after installing necessary NPM dependencies.Usage: `/npc-studio`
+    - `/ots` - Take screenshot and analyze with vision model. Usage: `/ots filename=<output_file_name_for_screenshot>` then select an area, and you will be prompted for your request.
+    - `/plan` - Execute a plan command. Usage: `/plan 'idea for a cron job to be set up to accomplish'`
+    - `/plonk` - Use vision model to interact with GUI. Usage: `/plonk '<task description>' `
+    - `/pti` - Use pardon-the-interruption mode to interact with reasoning model LLM. Usage: `/pti`
+    - `/rag` - Execute a RAG command using ChromaDB embeddings with optional file input (-f/--file). Usage: `/rag '<query_to_rag>' --emodel <NPCSH_EMBEDDING_MODEL> --eprovider <NPCSH_EMBEDDING_PROVIDER>`
+    - `/roll` - generate a video with video generation model. Usage: `/roll '<description_for_a_movie>' --vgmodel <NPCSH_VIDEO_GEN_MODEL> --vgprovider <NPCSH_VIDEO_GEN_PROVIDER>`
+    - `/sample` - Send a context-free prompt to an LLM, letting you get fresh answers without needing to start a separate conversation/shell. Usage: `/sample -m <NPCSH_CHAT_MODEL> 'question to sample --temp <float> --top_k int`
+    - `/search` - Execute a web search command. Usage: `/search 'search query' --sprovider <provider>` where provider is currently limited to DuckDuckGo and Perplexity. Wikipedia integration ongoing.
+    - `/serve` - Serve an NPC Team server.
+    - `/set` - Set configuration values.
+      - Usage:
+        - `/set model gemma3:4b`,
+        - `/set provider ollama`,
+        - `/set NPCSH_VIDEO_GEN_PROVIDER diffusers`
+    - `/sleep` - Evolve knowledge graph with options for dreaming.  Usage: `/sleep --ops link_facts,deepen`
+    - `/spool` - Enter interactive chat (spool) mode with an npc with fresh context or files for rag. Usage: `/spool --attachments 'path1,path2,path3' -n <npc_name> -m <modell> -p <provider>`
+    - `/trigger` - Execute a trigger command.  Usage: `/trigger 'a description of a trigger to implement with system daemons/file system listeners.' -m gemma3:27b -p ollama`
+    - `/vixynt` - Generate and edit images from text descriptions using local models, openai, gemini.
+      - Usage:
+        - Gen Image: `/vixynt -igp <NPCSH_IMAGE_GEN_PROVIDER> --igmodel <NPCSH_IMAGE_GEN_MODEL> --output_file <path_to_file> width=<int:1024> height =<int:1024> 'description of image`
+        - Edit Image: `/vixynt 'edit this....' --attachments '/path/to/image.png,/path/to/image.jpeg'`
+    - `/wander` - A method for LLMs to think on a problem by switching between states of high temperature and low temperature.  Usage: `/wander 'query to wander about' --provider "ollama" --model "deepseek-r1:32b" environment="a vast dark ocean" interruption-likelihood=.1`
+    - `/yap` - Enter voice chat (yap) mode. Usage: `/yap -n <npc_to_chat_with>`
     ## Common Command-Line Flags:
@@ -372,23 +392,38 @@ python-tkinter (pyautogui)
 </details>
 ## Startup Configuration and Project Structure
-After `npcsh` has been pip installed, `npcsh`, `corca`, `guac`, `pti`, `spool`, `yap` and the `npc` CLI can be used as command line tools. To initialize these correctly, first start by starting the NPC shell:
+To initialize the NPC shell environment parameters correctly, first start the NPC shell:
 ```bash
 npcsh
 ```
-When initialized, `npcsh` will generate a .npcshrc file in your home directory that stores your npcsh settings.
-Here is an example of what the .npcshrc file might look like after this has been run.
+When initialized, `npcsh` will generate a `.npcshrc` file in your home directory that stores your npcsh settings.
+Here is an example of what the `.npcshrc` file might look like after this has been run.
 ```bash
 # NPCSH Configuration File
 export NPCSH_INITIALIZED=1
-export NPCSH_CHAT_PROVIDER='ollama'
-export NPCSH_CHAT_MODEL='llama3.2'
 export NPCSH_DB_PATH='~/npcsh_history.db'
+export NPCSH_CHAT_MODEL=gemma3:4b
+export NPCSH_CHAT_PROVIDER=ollama
+export NPCSH_DEFAULT_MODE=agent
+export NPCSH_EMBEDDING_MODEL=nomic-embed-text
+export NPCSH_EMBEDDING_PROVIDER=ollama
+export NPCSH_IMAGE_GEN_MODEL=gpt-image-1
+export NPCSH_IMAGE_GEN_PROVIDER=openai
+export NPCSH_INITIALIZED=1
+export NPCSH_REASONING_MODEL=deepseek-r1
+export NPCSH_REASONING_PROVIDER=deepseek
+export NPCSH_SEARCH_PROVIDER=duckduckgo
+export NPCSH_STREAM_OUTPUT=1
+export NPCSH_VECTOR_DB_PATH=~/npcsh_chroma.db
+export NPCSH_VIDEO_GEN_MODEL=runwayml/stable-diffusion-v1-5
+export NPCSH_VIDEO_GEN_PROVIDER=diffusers
+export NPCSH_VISION_MODEL=gpt-4o-mini
+export NPCSH_VISION_PROVIDER=openai
 ```
-`npcsh` also comes with a set of jinxs 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.
+`npcsh` also comes with a set of jinxs 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.
-The 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:
+The 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`:
 ```bash
 # Source NPCSH configuration
@@ -399,7 +434,7 @@ fi
 We 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.
-To 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:
+To 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:
 ```bash
 export OPENAI_API_KEY="your_openai_key"
@@ -411,14 +446,15 @@ export PERPLEXITY_API_KEY='your_perplexity_key'
  Individual npcs can also be set to use different models and providers by setting the `model` and `provider` keys in the npc files.
- Once initialized and set up, you will find the following in your ~/.npcsh directory:
+ Once initialized and set up, you will find the following in your `~/.npcsh` directory:
 ```bash
 ~/.npcsh/
 ├── npc_team/           # Global NPCs
 │   ├── jinxs/          # Global tools
 │   └── assembly_lines/ # Workflow pipelines
-│   └── example.npc  # globally available npc
-│   └── global.ctx  # global context file
+│   └── sibiji.npc  # globally available npc
+│   └── npcsh.ctx  # global context file

{npcsh-1.0.17 → npcsh-1.0.19}/README.md RENAMED Viewed

@@ -5,21 +5,25 @@
 # NPC Shell
-The NPC shell is a suite of executable command-line programs that allow users to easily interact with NPCs and LLMs through a command line shell.
-Programs within the NPC shell use the properties defined in `~/.npcshrc`, which is generated upon installation and running of `npcsh` for the first time.
+The NPC shell is the toolkit for tomorrow, providing a suite of programs to make use of multi-modal LLMs and agents in novel interactive modes. `npcsh` is a command-line program, and so can be used wherever you work. `npcsh` is developed to work relibly with small models and performs excellently with the state-of-the-art models from major model providers.
 To get started:
-```
+```bash
+# for users who want to mainly use models through APIs (e.g. , gemini, grok, deepseek, anthropic, openai, mistral, , any others provided by litellm ):
+pip install 'npcsh[lite]'
+# for users who want to use local models (these install diffusers/transformers/torch stack so it is big.):
 pip install 'npcsh[local]'
+# for users who want to use the voice mode `yap`, see also the OS-specific installation instructions for installing needed system audio  libraries
+pip install 'npcsh[yap]'
 ```
-Once installed, the following CLI tools will be available: `npcsh`, `guac`, `npc` cli, `yap` `pti`, `wander`, and `spool`.
-# npcsh
-- An AI-powered shell that parses bash, natural language, and special macro calls, `npcsh` processes your input accordingly, agentically, and automatically.
+Once installed: run
+```bash
+npcsh
+```
+and you will enter the NPC shell. Additionally, the pip installation includes making the following CLI tools available in bash: `corca`, `guac`, `npc` cli, `pti`, `spool`, `wander`, and`yap`.
+# Usage
   - Get help with a task:
       ```bash
       npcsh:🤖sibiji:gemini-2.5-flash>can you help me identify what process is listening on port 5337?
@@ -37,18 +41,7 @@ Once installed, the following CLI tools will be available: `npcsh`, `guac`, `npc
     ```bash
     npcsh> has there ever been a better pasta shape than bucatini?
     ```
-    ```
-    Ultimately, the "best" pasta shape depends on personal preference and the dish being prepared. Bucatini shines in specific contexts, but pasta lovers often appreciate a diverse range of shapes for their unique qualities and compatibilities with various sauces and ingredients. Each shape has its place in the culinary world, and trying different types can enhance the overall dining experience.
-    ```
-    ```
-    .Loaded .env file...
-    Initializing database schema...
-    Database schema initialization complete.
-    Processing prompt: 'has there ever been a better pasta shape than bucatini?' with NPC: 'sibiji'...
-    • Action chosen: answer_question
-    • Explanation given: The question is a general opinion-based inquiry about pasta shapes and can be answered without external data or jinx invocation.
-    ...............................................................................
+    ```
     Bucatini is certainly a favorite for many due to its unique hollow center, which holds sauces beautifully. Whether it's "better" is subjective and depends on the dish and personal
     preference. Shapes like orecchiette, rigatoni, or trofie excel in different recipes. Bucatini stands out for its versatility and texture, making it a top contender among pasta shapes!
     ```
@@ -91,38 +84,67 @@ Once installed, the following CLI tools will be available: `npcsh`, `guac`, `npc
     ```bash
     /ots
     ```
+  - **Use an mcp server**: make use of NPCs with MCP servers.
+    ```bash
+    /corca --mcp-server-path /path.to.server.py
+    ```
+# NPC Data Layer
+The core of npcsh's capabilities is powered by the NPC Data Layer. Upon initialization, a user will be prompted to make a team in the current directory or to use a global team stored in `~/.npcsh/` which houses the NPC team with its jinxs, models, contexts, assembly lines. By implementing these components as simple data structures, users can focus on tweaking the relevant parts of their multi-agent systems.
+## Creating Custom Components
+Users can extend NPC capabilities through simple YAML files:
+- **NPCs** (.npc): are defined with a name, primary directive, and optional model specifications
+- **Jinxs** (.jinx): specify function-like capabilities with preprocessing, execution, and postprocessing steps
+- **Context** (.ctx): Specify contextual information, team preferences, MCP server paths, database connections, and other environment variables that are loaded for the team. Teams are specified by their path and the team name in the `<team>.ctx` file. Teams organize collections of NPCs with shared context and specify a coordinator within the team context
+The NPC Shell system integrates the capabilities of `npcpy` to maintain conversation history, track command execution, and provide intelligent autocomplete through an extensible command routing system. State is preserved between sessions, allowing for continuous knowledge building over time.
+This architecture enables complex AI workflows while maintaining a simple, declarative syntax that abstracts away implementation complexity. By organizing AI capabilities as composable data structures rather than code, npcsh creates a more accessible and adaptable framework for AI automation.
 # Macros
 -  activated by invoking `/<command> ...` in `npcsh`, macros can be called in bash or through the `npc` CLI. In our examples, we provide both `npcsh` calls as well as bash calls with the `npc` cli where relevant. For converting any `/<command>` in `npcsh` to a bash version, replace the `/` with `npc ` and the macro command will be invoked as a positional argument. Some, like breathe, flush,
-    - `/alicanto` - Conduct deep research with multiple perspectives, identifying gold insights and cliff warnings
-    - `/brainblast` - Execute an advanced chunked search on command history
-    - `/breathe` - Condense context on a regular cadence
-    - `/compile` - Compile NPC profiles
-    - `/corca` - Enter the Corca MCP-powered agentic shell. Usage: /corca [--mcp-server-path path]
-    - `/flush` - Flush the last N messages
-    - `/guac` - Enter guac mode
-    - `/help` - Show help for commands, NPCs, or Jinxs. Usage: /help
-    - `/init` - Initialize NPC project
-    - `/jinxs` - Show available jinxs for the current NPC/Team
-    - `/npc-studio` - Start npc studio
-    - `/ots` - Take screenshot and analyze with vision model
-    - `/plan` - Execute a plan command
-    - `/plonk` - Use vision model to interact with GUI. Usage: /plonk <task description>
-    - `/pti` - Use pardon-the-interruption mode to interact with reasoning model LLM
-    - `/rag` - Execute a RAG command using ChromaDB embeddings with optional file input (-f/--file)
-    - `/roll` - generate a video with video generation model
-    - `/sample` - Send a prompt directly to the LLM
-    - `/search` - Execute a web search command
-    - `/serve` - Serve an NPC Team server.
-    - `/set` - Set configuration values
-    - `/sleep` - Evolve knowledge graph with options for dreaming.
-    - `/spool` - Enter interactive chat (spool) mode with an npc with fresh context or files for rag
-    - `/trigger` - Execute a trigger command
-    - `/vixynt` - Generate and edit images from text descriptions using local models, openai, gemini
-    - `/wander` - A method for LLMs to think on a problem by switching between states of high temperature and low temperature
-    - `/yap` - Enter voice chat (yap) mode
+    - `/alicanto` - Conduct deep research with multiple perspectives, identifying gold insights and cliff warnings. Usage: `/alicanto 'query to be researched' --num-npcs <int> --depth <int>`
+    - `/brainblast` - Execute an advanced chunked search on command history. Usage:     `/brainblast 'query'  --top_k 10`
+    - `/breathe` - Condense context on a regular cadence. Usage: `/breathe -p <provider: NPCSH_CHAT_PROVIDER> -m <model: NPCSH_CHAT_MODEL>`
+    - `/compile` - Compile NPC profiles. Usage: `/compile <path_to_npc> `
+    - `/corca` - Enter the Corca MCP-powered agentic shell. Usage: `/corca [--mcp-server-path path]`
+    - `/flush` - Flush the last N messages. Usage: `/flush N=10`
+    - `/guac` - Enter guac mode. Usage: `/guac`
+    - `/help` - Show help for commands, NPCs, or Jinxs. Usage: `/help`
+    - `/init` - Initialize NPC project. Usage: `/init`
+    - `/jinxs` - Show available jinxs for the current NPC/Team. Usage: `/jinxs`
+    - `/<jinx_name>` - Run a jinx with specified command line arguments. `/<jinx_name> jinx_arg1 jinx_arg2`
+    - `/npc-studio` - Start npc studio. Pulls NPC Studio github to `~/.npcsh/npc-studio` and launches it in development mode after installing necessary NPM dependencies.Usage: `/npc-studio`
+    - `/ots` - Take screenshot and analyze with vision model. Usage: `/ots filename=<output_file_name_for_screenshot>` then select an area, and you will be prompted for your request.
+    - `/plan` - Execute a plan command. Usage: `/plan 'idea for a cron job to be set up to accomplish'`
+    - `/plonk` - Use vision model to interact with GUI. Usage: `/plonk '<task description>' `
+    - `/pti` - Use pardon-the-interruption mode to interact with reasoning model LLM. Usage: `/pti`
+    - `/rag` - Execute a RAG command using ChromaDB embeddings with optional file input (-f/--file). Usage: `/rag '<query_to_rag>' --emodel <NPCSH_EMBEDDING_MODEL> --eprovider <NPCSH_EMBEDDING_PROVIDER>`
+    - `/roll` - generate a video with video generation model. Usage: `/roll '<description_for_a_movie>' --vgmodel <NPCSH_VIDEO_GEN_MODEL> --vgprovider <NPCSH_VIDEO_GEN_PROVIDER>`
+    - `/sample` - Send a context-free prompt to an LLM, letting you get fresh answers without needing to start a separate conversation/shell. Usage: `/sample -m <NPCSH_CHAT_MODEL> 'question to sample --temp <float> --top_k int`
+    - `/search` - Execute a web search command. Usage: `/search 'search query' --sprovider <provider>` where provider is currently limited to DuckDuckGo and Perplexity. Wikipedia integration ongoing.
+    - `/serve` - Serve an NPC Team server.
+    - `/set` - Set configuration values.
+      - Usage:
+        - `/set model gemma3:4b`,
+        - `/set provider ollama`,
+        - `/set NPCSH_VIDEO_GEN_PROVIDER diffusers`
+    - `/sleep` - Evolve knowledge graph with options for dreaming.  Usage: `/sleep --ops link_facts,deepen`
+    - `/spool` - Enter interactive chat (spool) mode with an npc with fresh context or files for rag. Usage: `/spool --attachments 'path1,path2,path3' -n <npc_name> -m <modell> -p <provider>`
+    - `/trigger` - Execute a trigger command.  Usage: `/trigger 'a description of a trigger to implement with system daemons/file system listeners.' -m gemma3:27b -p ollama`
+    - `/vixynt` - Generate and edit images from text descriptions using local models, openai, gemini.
+      - Usage:
+        - Gen Image: `/vixynt -igp <NPCSH_IMAGE_GEN_PROVIDER> --igmodel <NPCSH_IMAGE_GEN_MODEL> --output_file <path_to_file> width=<int:1024> height =<int:1024> 'description of image`
+        - Edit Image: `/vixynt 'edit this....' --attachments '/path/to/image.png,/path/to/image.jpeg'`
+    - `/wander` - A method for LLMs to think on a problem by switching between states of high temperature and low temperature.  Usage: `/wander 'query to wander about' --provider "ollama" --model "deepseek-r1:32b" environment="a vast dark ocean" interruption-likelihood=.1`
+    - `/yap` - Enter voice chat (yap) mode. Usage: `/yap -n <npc_to_chat_with>`
     ## Common Command-Line Flags:
@@ -270,23 +292,38 @@ python-tkinter (pyautogui)
 </details>
 ## Startup Configuration and Project Structure
-After `npcsh` has been pip installed, `npcsh`, `corca`, `guac`, `pti`, `spool`, `yap` and the `npc` CLI can be used as command line tools. To initialize these correctly, first start by starting the NPC shell:
+To initialize the NPC shell environment parameters correctly, first start the NPC shell:
 ```bash
 npcsh
 ```
-When initialized, `npcsh` will generate a .npcshrc file in your home directory that stores your npcsh settings.
-Here is an example of what the .npcshrc file might look like after this has been run.
+When initialized, `npcsh` will generate a `.npcshrc` file in your home directory that stores your npcsh settings.
+Here is an example of what the `.npcshrc` file might look like after this has been run.
 ```bash
 # NPCSH Configuration File
 export NPCSH_INITIALIZED=1
-export NPCSH_CHAT_PROVIDER='ollama'
-export NPCSH_CHAT_MODEL='llama3.2'
 export NPCSH_DB_PATH='~/npcsh_history.db'
+export NPCSH_CHAT_MODEL=gemma3:4b
+export NPCSH_CHAT_PROVIDER=ollama
+export NPCSH_DEFAULT_MODE=agent
+export NPCSH_EMBEDDING_MODEL=nomic-embed-text
+export NPCSH_EMBEDDING_PROVIDER=ollama
+export NPCSH_IMAGE_GEN_MODEL=gpt-image-1
+export NPCSH_IMAGE_GEN_PROVIDER=openai
+export NPCSH_INITIALIZED=1
+export NPCSH_REASONING_MODEL=deepseek-r1
+export NPCSH_REASONING_PROVIDER=deepseek
+export NPCSH_SEARCH_PROVIDER=duckduckgo
+export NPCSH_STREAM_OUTPUT=1
+export NPCSH_VECTOR_DB_PATH=~/npcsh_chroma.db
+export NPCSH_VIDEO_GEN_MODEL=runwayml/stable-diffusion-v1-5
+export NPCSH_VIDEO_GEN_PROVIDER=diffusers
+export NPCSH_VISION_MODEL=gpt-4o-mini
+export NPCSH_VISION_PROVIDER=openai
 ```
-`npcsh` also comes with a set of jinxs 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.
+`npcsh` also comes with a set of jinxs 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.
-The 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:
+The 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`:
 ```bash
 # Source NPCSH configuration
@@ -297,7 +334,7 @@ fi
 We 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.
-To 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:
+To 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:
 ```bash
 export OPENAI_API_KEY="your_openai_key"
@@ -309,14 +346,15 @@ export PERPLEXITY_API_KEY='your_perplexity_key'
  Individual npcs can also be set to use different models and providers by setting the `model` and `provider` keys in the npc files.
- Once initialized and set up, you will find the following in your ~/.npcsh directory:
+ Once initialized and set up, you will find the following in your `~/.npcsh` directory:
 ```bash
 ~/.npcsh/
 ├── npc_team/           # Global NPCs
 │   ├── jinxs/          # Global tools
 │   └── assembly_lines/ # Workflow pipelines
-│   └── example.npc  # globally available npc
-│   └── global.ctx  # global context file
+│   └── sibiji.npc  # globally available npc
+│   └── npcsh.ctx  # global context file

{npcsh-1.0.17 → npcsh-1.0.19}/npcsh/_state.py RENAMED Viewed

@@ -1860,7 +1860,8 @@ def should_skip_kg_processing(user_input: str, assistant_output: str) -> bool:
 def execute_slash_command(command: str,
                           stdin_input: Optional[str],
                           state: ShellState,
-                          stream: bool, router) -> Tuple[ShellState, Any]:
+                          stream: bool,
+                          router) -> Tuple[ShellState, Any]:
     """Executes slash commands using the router or checking NPC/Team jinxs."""
     all_command_parts = shlex.split(command)
     command_name = all_command_parts[0].lstrip('/')
@@ -2034,7 +2035,11 @@ def process_pipeline_command(
     exec_provider = provider_override or npc_provider or state.chat_provider
     if cmd_to_process.startswith("/"):
-        return execute_slash_command(cmd_to_process, stdin_input, state, stream_final, router)
+        return execute_slash_command(cmd_to_process,
+                                     stdin_input,
+                                     state,
+                                     stream_final,
+                                     router)
     cmd_parts = parse_command_safely(cmd_to_process)
     if not cmd_parts:
@@ -2217,12 +2222,13 @@ def execute_command(
                         if stream_this_segment:
                             full_stream_output = print_and_process_stream_with_markdown(output,
                                                                                         state.npc.model,
-                                                                                        state.npc.provider, show=True)
+                                                                                        state.npc.provider,
+                                                                                        show=True)
                             stdin_for_next = full_stream_output
                             if is_last_command:
                                 final_output = full_stream_output
                     except:
-                        if output is not None: # Try converting other types to string
+                        if output is not None:
                             try:
                                 stdin_for_next = str(output)
                             except Exception:
@@ -2446,6 +2452,7 @@ def process_result(
     result_state: ShellState,
     output: Any,
     command_history: CommandHistory,
 ):
@@ -2482,12 +2489,10 @@ def process_result(
         render_markdown(output.get('output'))
     elif result_state.stream_output:
         final_output_str = print_and_process_stream_with_markdown(output_content,
-                                                                  model_for_stream,
-                                                                  provider_for_stream,
-                                                                  show=True)
+                                                                    model_for_stream,
+                                                                    provider_for_stream,
+                                                                    show=True)
     elif output_content is not None:
         final_output_str = str(output_content)
         render_markdown(final_output_str)
@@ -2518,7 +2523,6 @@ def process_result(
             pdb.set_trace()
             try:
                 if not should_skip_kg_processing(user_input, final_output_str):
                     npc_kg = load_kg_from_db(engine, team_name, npc_name, result_state.current_path)
                     evolved_npc_kg, _ = kg_evolve_incremental(
                         existing_kg=npc_kg,
@@ -2528,9 +2532,7 @@ def process_result(
                         get_concepts=True,
                         link_concepts_facts = False,
                         link_concepts_concepts = False,
-                        link_facts_facts = False,
+                        link_facts_facts = False,
                     )
                     save_kg_to_db(engine,
                                 evolved_npc_kg,
@@ -2567,7 +2569,9 @@ def process_result(
                     Respond with JSON: {{"suggestion": "Your sentence."
                     }}"""
-                    response = get_llm_response(prompt, npc=active_npc, format="json")
+                    response = get_llm_response(prompt,
+                                                npc=active_npc,
+                                                format="json")
                     suggestion = response.get("response", {}).get("suggestion")
                     if suggestion:

{npcsh-1.0.17 → npcsh-1.0.19}/npcsh/npcsh.py RENAMED Viewed

@@ -206,7 +206,8 @@ def run_repl(command_history: CommandHistory, initial_state: ShellState):
             process_result(user_input,
                            state,
                            output,
-                           command_history)
+                           command_history,
+                           already_printed=False)
         except KeyboardInterrupt:
             if is_windows:

{npcsh-1.0.17 → npcsh-1.0.19}/npcsh/routes.py RENAMED Viewed

@@ -612,9 +612,7 @@ def brainblast_handler(command: str, **kwargs):
         return {"output": f"Error executing brainblast command: {e}", "messages": messages}
 @router.route("rag", "Execute a RAG command using ChromaDB embeddings with optional file input (-f/--file)")
-def rag_handler(command: str, **kwargs):
-    messages = safe_get(kwargs, "messages", [])
+def rag_handler(command: str, **kwargs):
     parts = shlex.split(command)
     user_command = []
     file_paths = []
@@ -640,7 +638,7 @@ def rag_handler(command: str, **kwargs):
     embedding_provider = safe_get(kwargs, "eprovider", NPCSH_EMBEDDING_PROVIDER)
     if not user_command and not file_paths:
-        return {"output": "Usage: /rag [-f file_path] <query>", "messages": messages}
+        return {"output": "Usage: /rag [-f file_path] <query>", "messages": kwargs.get('messages', [])}
     try:
         # Process files if provided
@@ -652,9 +650,7 @@ def rag_handler(command: str, **kwargs):
                 file_contents.extend([f"[{file_name}] {chunk}" for chunk in chunks])
             except Exception as file_err:
                 file_contents.append(f"Error processing file {file_path}: {str(file_err)}")
-        # Execute the RAG command
-        return execute_rag_command(
+        exe_rag =  execute_rag_command(
             command=user_command,
             vector_db_path=vector_db_path,
             embedding_model=embedding_model,
@@ -662,10 +658,11 @@ def rag_handler(command: str, **kwargs):
             file_contents=file_contents if file_paths else None,
             **kwargs
         )
+        return {'output':exe_rag.get('response'), 'messages': exe_rag.get('messages', kwargs.get('messages', []))}
     except Exception as e:
         traceback.print_exc()
-        return {"output": f"Error executing RAG command: {e}", "messages": messages}
+        return {"output": f"Error executing RAG command: {e}", "messages": kwargs.get('messages', [])}
 @router.route("roll", "generate a video")
 def roll_handler(command: str, **kwargs):
     messages = safe_get(kwargs, "messages", [])

{npcsh-1.0.17 → npcsh-1.0.19}/npcsh.egg-info/PKG-INFO RENAMED Viewed

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: npcsh
-Version: 1.0.17
+Version: 1.0.19
 Summary: npcsh is a command-line toolkit for using AI agents in novel ways.
 Home-page: https://github.com/NPC-Worldwide/npcsh
 Author: Christopher Agostino
@@ -43,6 +43,7 @@ Requires-Dist: redis
 Requires-Dist: psycopg2-binary
 Requires-Dist: flask_sse
 Requires-Dist: wikipedia
+Requires-Dist: mcp
 Provides-Extra: lite
 Requires-Dist: anthropic; extra == "lite"
 Requires-Dist: openai; extra == "lite"
@@ -65,8 +66,6 @@ Requires-Dist: playsound==1.2.2; extra == "yap"
 Requires-Dist: pygame; extra == "yap"
 Requires-Dist: faster_whisper; extra == "yap"
 Requires-Dist: pyttsx3; extra == "yap"
-Provides-Extra: mcp
-Requires-Dist: mcp; extra == "mcp"
 Provides-Extra: all
 Requires-Dist: anthropic; extra == "all"
 Requires-Dist: openai; extra == "all"
@@ -87,7 +86,6 @@ Requires-Dist: playsound==1.2.2; extra == "all"
 Requires-Dist: pygame; extra == "all"
 Requires-Dist: faster_whisper; extra == "all"
 Requires-Dist: pyttsx3; extra == "all"
-Requires-Dist: mcp; extra == "all"
 Dynamic: author
 Dynamic: author-email
 Dynamic: classifier
@@ -107,21 +105,25 @@ Dynamic: summary
 # NPC Shell
-The NPC shell is a suite of executable command-line programs that allow users to easily interact with NPCs and LLMs through a command line shell.
-Programs within the NPC shell use the properties defined in `~/.npcshrc`, which is generated upon installation and running of `npcsh` for the first time.
+The NPC shell is the toolkit for tomorrow, providing a suite of programs to make use of multi-modal LLMs and agents in novel interactive modes. `npcsh` is a command-line program, and so can be used wherever you work. `npcsh` is developed to work relibly with small models and performs excellently with the state-of-the-art models from major model providers.
 To get started:
-```
+```bash
+# for users who want to mainly use models through APIs (e.g. , gemini, grok, deepseek, anthropic, openai, mistral, , any others provided by litellm ):
+pip install 'npcsh[lite]'
+# for users who want to use local models (these install diffusers/transformers/torch stack so it is big.):
 pip install 'npcsh[local]'
+# for users who want to use the voice mode `yap`, see also the OS-specific installation instructions for installing needed system audio  libraries
+pip install 'npcsh[yap]'
 ```
-Once installed, the following CLI tools will be available: `npcsh`, `guac`, `npc` cli, `yap` `pti`, `wander`, and `spool`.
-# npcsh
-- An AI-powered shell that parses bash, natural language, and special macro calls, `npcsh` processes your input accordingly, agentically, and automatically.
+Once installed: run
+```bash
+npcsh
+```
+and you will enter the NPC shell. Additionally, the pip installation includes making the following CLI tools available in bash: `corca`, `guac`, `npc` cli, `pti`, `spool`, `wander`, and`yap`.
+# Usage
   - Get help with a task:
       ```bash
       npcsh:🤖sibiji:gemini-2.5-flash>can you help me identify what process is listening on port 5337?
@@ -139,18 +141,7 @@ Once installed, the following CLI tools will be available: `npcsh`, `guac`, `npc
     ```bash
     npcsh> has there ever been a better pasta shape than bucatini?
     ```
-    ```
-    Ultimately, the "best" pasta shape depends on personal preference and the dish being prepared. Bucatini shines in specific contexts, but pasta lovers often appreciate a diverse range of shapes for their unique qualities and compatibilities with various sauces and ingredients. Each shape has its place in the culinary world, and trying different types can enhance the overall dining experience.
-    ```
-    ```
-    .Loaded .env file...
-    Initializing database schema...
-    Database schema initialization complete.
-    Processing prompt: 'has there ever been a better pasta shape than bucatini?' with NPC: 'sibiji'...
-    • Action chosen: answer_question
-    • Explanation given: The question is a general opinion-based inquiry about pasta shapes and can be answered without external data or jinx invocation.
-    ...............................................................................
+    ```
     Bucatini is certainly a favorite for many due to its unique hollow center, which holds sauces beautifully. Whether it's "better" is subjective and depends on the dish and personal
     preference. Shapes like orecchiette, rigatoni, or trofie excel in different recipes. Bucatini stands out for its versatility and texture, making it a top contender among pasta shapes!
     ```
@@ -193,38 +184,67 @@ Once installed, the following CLI tools will be available: `npcsh`, `guac`, `npc
     ```bash
     /ots
     ```
+  - **Use an mcp server**: make use of NPCs with MCP servers.
+    ```bash
+    /corca --mcp-server-path /path.to.server.py
+    ```
+# NPC Data Layer
+The core of npcsh's capabilities is powered by the NPC Data Layer. Upon initialization, a user will be prompted to make a team in the current directory or to use a global team stored in `~/.npcsh/` which houses the NPC team with its jinxs, models, contexts, assembly lines. By implementing these components as simple data structures, users can focus on tweaking the relevant parts of their multi-agent systems.
+## Creating Custom Components
+Users can extend NPC capabilities through simple YAML files:
+- **NPCs** (.npc): are defined with a name, primary directive, and optional model specifications
+- **Jinxs** (.jinx): specify function-like capabilities with preprocessing, execution, and postprocessing steps
+- **Context** (.ctx): Specify contextual information, team preferences, MCP server paths, database connections, and other environment variables that are loaded for the team. Teams are specified by their path and the team name in the `<team>.ctx` file. Teams organize collections of NPCs with shared context and specify a coordinator within the team context
+The NPC Shell system integrates the capabilities of `npcpy` to maintain conversation history, track command execution, and provide intelligent autocomplete through an extensible command routing system. State is preserved between sessions, allowing for continuous knowledge building over time.
+This architecture enables complex AI workflows while maintaining a simple, declarative syntax that abstracts away implementation complexity. By organizing AI capabilities as composable data structures rather than code, npcsh creates a more accessible and adaptable framework for AI automation.
 # Macros
 -  activated by invoking `/<command> ...` in `npcsh`, macros can be called in bash or through the `npc` CLI. In our examples, we provide both `npcsh` calls as well as bash calls with the `npc` cli where relevant. For converting any `/<command>` in `npcsh` to a bash version, replace the `/` with `npc ` and the macro command will be invoked as a positional argument. Some, like breathe, flush,
-    - `/alicanto` - Conduct deep research with multiple perspectives, identifying gold insights and cliff warnings
-    - `/brainblast` - Execute an advanced chunked search on command history
-    - `/breathe` - Condense context on a regular cadence
-    - `/compile` - Compile NPC profiles
-    - `/corca` - Enter the Corca MCP-powered agentic shell. Usage: /corca [--mcp-server-path path]
-    - `/flush` - Flush the last N messages
-    - `/guac` - Enter guac mode
-    - `/help` - Show help for commands, NPCs, or Jinxs. Usage: /help
-    - `/init` - Initialize NPC project
-    - `/jinxs` - Show available jinxs for the current NPC/Team
-    - `/npc-studio` - Start npc studio
-    - `/ots` - Take screenshot and analyze with vision model
-    - `/plan` - Execute a plan command
-    - `/plonk` - Use vision model to interact with GUI. Usage: /plonk <task description>
-    - `/pti` - Use pardon-the-interruption mode to interact with reasoning model LLM
-    - `/rag` - Execute a RAG command using ChromaDB embeddings with optional file input (-f/--file)
-    - `/roll` - generate a video with video generation model
-    - `/sample` - Send a prompt directly to the LLM
-    - `/search` - Execute a web search command
-    - `/serve` - Serve an NPC Team server.
-    - `/set` - Set configuration values
-    - `/sleep` - Evolve knowledge graph with options for dreaming.
-    - `/spool` - Enter interactive chat (spool) mode with an npc with fresh context or files for rag
-    - `/trigger` - Execute a trigger command
-    - `/vixynt` - Generate and edit images from text descriptions using local models, openai, gemini
-    - `/wander` - A method for LLMs to think on a problem by switching between states of high temperature and low temperature
-    - `/yap` - Enter voice chat (yap) mode
+    - `/alicanto` - Conduct deep research with multiple perspectives, identifying gold insights and cliff warnings. Usage: `/alicanto 'query to be researched' --num-npcs <int> --depth <int>`
+    - `/brainblast` - Execute an advanced chunked search on command history. Usage:     `/brainblast 'query'  --top_k 10`
+    - `/breathe` - Condense context on a regular cadence. Usage: `/breathe -p <provider: NPCSH_CHAT_PROVIDER> -m <model: NPCSH_CHAT_MODEL>`
+    - `/compile` - Compile NPC profiles. Usage: `/compile <path_to_npc> `
+    - `/corca` - Enter the Corca MCP-powered agentic shell. Usage: `/corca [--mcp-server-path path]`
+    - `/flush` - Flush the last N messages. Usage: `/flush N=10`
+    - `/guac` - Enter guac mode. Usage: `/guac`
+    - `/help` - Show help for commands, NPCs, or Jinxs. Usage: `/help`
+    - `/init` - Initialize NPC project. Usage: `/init`
+    - `/jinxs` - Show available jinxs for the current NPC/Team. Usage: `/jinxs`
+    - `/<jinx_name>` - Run a jinx with specified command line arguments. `/<jinx_name> jinx_arg1 jinx_arg2`
+    - `/npc-studio` - Start npc studio. Pulls NPC Studio github to `~/.npcsh/npc-studio` and launches it in development mode after installing necessary NPM dependencies.Usage: `/npc-studio`
+    - `/ots` - Take screenshot and analyze with vision model. Usage: `/ots filename=<output_file_name_for_screenshot>` then select an area, and you will be prompted for your request.
+    - `/plan` - Execute a plan command. Usage: `/plan 'idea for a cron job to be set up to accomplish'`
+    - `/plonk` - Use vision model to interact with GUI. Usage: `/plonk '<task description>' `
+    - `/pti` - Use pardon-the-interruption mode to interact with reasoning model LLM. Usage: `/pti`
+    - `/rag` - Execute a RAG command using ChromaDB embeddings with optional file input (-f/--file). Usage: `/rag '<query_to_rag>' --emodel <NPCSH_EMBEDDING_MODEL> --eprovider <NPCSH_EMBEDDING_PROVIDER>`
+    - `/roll` - generate a video with video generation model. Usage: `/roll '<description_for_a_movie>' --vgmodel <NPCSH_VIDEO_GEN_MODEL> --vgprovider <NPCSH_VIDEO_GEN_PROVIDER>`
+    - `/sample` - Send a context-free prompt to an LLM, letting you get fresh answers without needing to start a separate conversation/shell. Usage: `/sample -m <NPCSH_CHAT_MODEL> 'question to sample --temp <float> --top_k int`
+    - `/search` - Execute a web search command. Usage: `/search 'search query' --sprovider <provider>` where provider is currently limited to DuckDuckGo and Perplexity. Wikipedia integration ongoing.
+    - `/serve` - Serve an NPC Team server.
+    - `/set` - Set configuration values.
+      - Usage:
+        - `/set model gemma3:4b`,
+        - `/set provider ollama`,
+        - `/set NPCSH_VIDEO_GEN_PROVIDER diffusers`
+    - `/sleep` - Evolve knowledge graph with options for dreaming.  Usage: `/sleep --ops link_facts,deepen`
+    - `/spool` - Enter interactive chat (spool) mode with an npc with fresh context or files for rag. Usage: `/spool --attachments 'path1,path2,path3' -n <npc_name> -m <modell> -p <provider>`
+    - `/trigger` - Execute a trigger command.  Usage: `/trigger 'a description of a trigger to implement with system daemons/file system listeners.' -m gemma3:27b -p ollama`
+    - `/vixynt` - Generate and edit images from text descriptions using local models, openai, gemini.
+      - Usage:
+        - Gen Image: `/vixynt -igp <NPCSH_IMAGE_GEN_PROVIDER> --igmodel <NPCSH_IMAGE_GEN_MODEL> --output_file <path_to_file> width=<int:1024> height =<int:1024> 'description of image`
+        - Edit Image: `/vixynt 'edit this....' --attachments '/path/to/image.png,/path/to/image.jpeg'`
+    - `/wander` - A method for LLMs to think on a problem by switching between states of high temperature and low temperature.  Usage: `/wander 'query to wander about' --provider "ollama" --model "deepseek-r1:32b" environment="a vast dark ocean" interruption-likelihood=.1`
+    - `/yap` - Enter voice chat (yap) mode. Usage: `/yap -n <npc_to_chat_with>`
     ## Common Command-Line Flags:
@@ -372,23 +392,38 @@ python-tkinter (pyautogui)
 </details>
 ## Startup Configuration and Project Structure
-After `npcsh` has been pip installed, `npcsh`, `corca`, `guac`, `pti`, `spool`, `yap` and the `npc` CLI can be used as command line tools. To initialize these correctly, first start by starting the NPC shell:
+To initialize the NPC shell environment parameters correctly, first start the NPC shell:
 ```bash
 npcsh
 ```
-When initialized, `npcsh` will generate a .npcshrc file in your home directory that stores your npcsh settings.
-Here is an example of what the .npcshrc file might look like after this has been run.
+When initialized, `npcsh` will generate a `.npcshrc` file in your home directory that stores your npcsh settings.
+Here is an example of what the `.npcshrc` file might look like after this has been run.
 ```bash
 # NPCSH Configuration File
 export NPCSH_INITIALIZED=1
-export NPCSH_CHAT_PROVIDER='ollama'
-export NPCSH_CHAT_MODEL='llama3.2'
 export NPCSH_DB_PATH='~/npcsh_history.db'
+export NPCSH_CHAT_MODEL=gemma3:4b
+export NPCSH_CHAT_PROVIDER=ollama
+export NPCSH_DEFAULT_MODE=agent
+export NPCSH_EMBEDDING_MODEL=nomic-embed-text
+export NPCSH_EMBEDDING_PROVIDER=ollama
+export NPCSH_IMAGE_GEN_MODEL=gpt-image-1
+export NPCSH_IMAGE_GEN_PROVIDER=openai
+export NPCSH_INITIALIZED=1
+export NPCSH_REASONING_MODEL=deepseek-r1
+export NPCSH_REASONING_PROVIDER=deepseek
+export NPCSH_SEARCH_PROVIDER=duckduckgo
+export NPCSH_STREAM_OUTPUT=1
+export NPCSH_VECTOR_DB_PATH=~/npcsh_chroma.db
+export NPCSH_VIDEO_GEN_MODEL=runwayml/stable-diffusion-v1-5
+export NPCSH_VIDEO_GEN_PROVIDER=diffusers
+export NPCSH_VISION_MODEL=gpt-4o-mini
+export NPCSH_VISION_PROVIDER=openai
 ```
-`npcsh` also comes with a set of jinxs 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.
+`npcsh` also comes with a set of jinxs 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.
-The 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:
+The 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`:
 ```bash
 # Source NPCSH configuration
@@ -399,7 +434,7 @@ fi
 We 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.
-To 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:
+To 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:
 ```bash
 export OPENAI_API_KEY="your_openai_key"
@@ -411,14 +446,15 @@ export PERPLEXITY_API_KEY='your_perplexity_key'
  Individual npcs can also be set to use different models and providers by setting the `model` and `provider` keys in the npc files.
- Once initialized and set up, you will find the following in your ~/.npcsh directory:
+ Once initialized and set up, you will find the following in your `~/.npcsh` directory:
 ```bash
 ~/.npcsh/
 ├── npc_team/           # Global NPCs
 │   ├── jinxs/          # Global tools
 │   └── assembly_lines/ # Workflow pipelines
-│   └── example.npc  # globally available npc
-│   └── global.ctx  # global context file
+│   └── sibiji.npc  # globally available npc
+│   └── npcsh.ctx  # global context file

{npcsh-1.0.17 → npcsh-1.0.19}/npcsh.egg-info/requires.txt RENAMED Viewed

@@ -31,6 +31,7 @@ redis
 psycopg2-binary
 flask_sse
 wikipedia
+mcp
 [all]
 anthropic
@@ -52,7 +53,6 @@ playsound==1.2.2
 pygame
 faster_whisper
 pyttsx3
-mcp
 [lite]
 anthropic
@@ -71,9 +71,6 @@ nltk
 torch
 darts
-[mcp]
-mcp
 [yap]
 pyaudio
 gtts

{npcsh-1.0.17 → npcsh-1.0.19}/setup.py RENAMED Viewed

@@ -40,6 +40,7 @@ base_requirements = [
     "psycopg2-binary",
     "flask_sse",
     "wikipedia",
+    "mcp"
 ]
 # API integration requirements
@@ -50,10 +51,6 @@ api_requirements = [
     "google-genai",
 ]
-# mcp integration requirements
-mcp_requirements = [
-    "mcp",
-]
 # Local ML/AI requirements
 local_requirements = [
     "sentence_transformers",
@@ -81,15 +78,14 @@ extra_files = package_files("npcpy/npc_team/")
 setup(
     name="npcsh",
-    version="1.0.17",
+    version="1.0.19",
     packages=find_packages(exclude=["tests*"]),
     install_requires=base_requirements,  # Only install base requirements by default
     extras_require={
-        "lite": api_requirements,  # Just API integrations
-        "local": local_requirements,  # Local AI/ML features
-        "yap": voice_requirements,  # Voice/Audio features
-    "mcp": mcp_requirements,  # MCP integration
-        "all": api_requirements + local_requirements + voice_requirements + mcp_requirements,  # Everything
+        "lite": api_requirements,
+        "local": local_requirements,
+        "yap": voice_requirements,
+        "all": api_requirements + local_requirements + voice_requirements ,
     },
     entry_points={
         "console_scripts": [