npcsh 1.1.7__tar.gz → 1.1.8__tar.gz

{npcsh-1.1.7 → npcsh-1.1.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: npcsh
-Version: 1.1.7
+Version: 1.1.8
 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
@@ -143,17 +143,49 @@ and you will enter the NPC shell. Additionally, the pip installation includes th
       ```
 
 
-  - **Search the Web**
+  - **Search**
+    - search the web
     ```bash
-    /search "cal golden bears football schedule" -sp perplexity
+    /search "cerulean city" perplexity
+
     ```
     <p align="center">
-        <img src="https://raw.githubusercontent.com/npc-worldwide/npcsh/main/test_data/search_example.png" alt="example of search results", width=600>
-     </p>
+        <img src="https://raw.githubusercontent.com/npc-worldwide/npcsh/main/test_data/search.gif" alt="example of search results", width=600>
+    </p>
+    
+    - search approved memories
+    ```bash
+    /search query="how to deploy python apps" memory=true
+    ```
+        
+    - search the knowledge graph
+
+    ```bash
+    /search query="user preferences for database" kg=true
+    ```
+        
+    - execute a RAG search across files
+
+    ```bash
+    /search --rag -f ~/docs/api.md,~/docs/config.yaml "authentication setup"
+    ```
+        
+    - brainblast search (searches many keyword combinations)
+
+    ```bash
+    /search query="git commands" brainblast=true
+    ```
+        
+    - web search with specific provider
+
+    ```bash
+    /search query="family vacations" sprovider="perplexity"
+    ```     
 
   - **Computer Use**
+
     ```bash
-    /plonk 'find out the latest news on cnn'
+    /plonk 'find out the latest news on cnn' gemma3:12b ollama
     ```
 
   - **Generate Image**
@@ -165,12 +197,12 @@ and you will enter the NPC shell. Additionally, the pip installation includes th
       </p>
   - **Generate Video**
     ```bash
-    /roll 'generate a video of a hat riding a dog'
+    /roll 'generate a video of a hat riding a dog' veo-3.1-fast-generate-preview  gemini
     ```
-    <!--
+
       <p align="center">
-        <img src="https://raw.githubusercontent.com/npc-worldwide/npcsh/main/test_data/hat_video.mp4" alt="video of a hat riding a dog", width=250>
-      </p> -->
+        <img src="https://raw.githubusercontent.com/NPC-Worldwide/npcsh/main/test_data/hatridingdog.gif" alt="video of a hat riding a dog", width=250>
+      </p> 
 
   - **Serve an NPC Team**
     ```bash
@@ -212,16 +244,13 @@ This architecture enables users to build complex AI workflows while maintaining
 
 Importantly, users can switch easily between the NPCs they are chatting with by typing `/n npc_name` within the NPC shell. Likewise, they can create Jinxs and then use them from within the NPC shell by invoking the jinx name and the arguments required for the Jinx;  `/<jinx_name> arg1 arg2`
 
-# 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,
-    
+# Jinx as macros
+-  activated by invoking `/<jinx_name> ...` in `npcsh`, jinxs 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. 
     - `/alicanto` - Conduct deep research with multiple perspectives, identifying gold insights and cliff warnings. Usage: `/alicanto 'query to be researched' --num-npcs <int> --depth <int>`
     - `/build` - Builds the current npc team to an executable format . Usage: `/build <output[flask,docker,cli,static]> --options`
-    - `/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`
@@ -229,13 +258,11 @@ Importantly, users can switch easily between the NPCs they are chatting with by
     - `/<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.
+    - `/search` - Execute a search command on the web, in your memories, in the knowledge graph, or in documents with rag. Usage: `/search 'search query' --sprovider <provider>` where provider is currently limited to DuckDuckGo, Perplexity, and Exa with more coming soon through litellm. Wikipedia integration ongoing. See above for more search specific examples.
     - `/serve` - Serve an NPC Team server. 
     - `/set` - Set configuration values. 
       - Usage: 
@@ -249,7 +276,6 @@ Importantly, users can switch easily between the NPCs they are chatting with by
       - 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>`
     
@@ -271,24 +297,26 @@ Importantly, users can switch easily between the NPCs they are chatting with by
     '
 
 ## Read the Docs
-To see more about how to use the macros and modes in the NPC Shell, read the docs at [npc-shell.readthedocs.io](https://npc-shell.readthedocs.io/en/latest/)
+To see more about how to use the jinxs and modes in the NPC Shell, read the docs at [npc-shell.readthedocs.io](https://npc-shell.readthedocs.io/en/latest/)
 
 
 ## Inference Capabilities
 - `npcsh` works with local and enterprise LLM providers through its LiteLLM integration, allowing users to run inference from Ollama, LMStudio, vLLM, MLX, OpenAI, Anthropic, Gemini, and Deepseek, making it a versatile tool for both simple commands and sophisticated AI-driven tasks. 
 
 ## NPC Studio
-There is a graphical user interface that makes use of the NPC Toolkit through the NPC Studio. See the source code for NPC Studio [here](https://github.com/npc-worldwide/npc-studio). Download the executables at [our website](https://enpisi.com/npc-studio). For the most up to date version, you can use NPC Studio by invoking it in npcsh 
+There is a graphical user interface that makes use of the NPC Toolkit through the NPC Studio. See the source code for NPC Studio [here](https://github.com/npc-worldwide/npc-studio). Download the executables at [our website](https://enpisi.com/downloads). For the most up to date development version, you can use NPC Studio by invoking it in npcsh 
+
 ```
 /npc-studio
 ```
-which will download and set up and serve the NPC Studio application within your `~/.npcsh` folder. It requires `npm` and `node` to work.
+which will download and set up and serve the NPC Studio application within your `~/.npcsh` folder. It requires `npm` and `node` to work, and of course npcpy !
 
-## Mailing List
+## Mailing List and Community
 Interested 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)!
 
+[Join the discord to discuss ideas for npc tools](https://discord.gg/VvYVT5YC)
 ## Support
-If you appreciate the work here, [consider supporting NPC Worldwide with a monthly donation](https://buymeacoffee.com/npcworldwide), [buying NPC-WW themed merch](https://enpisi.com/shop), or hiring us to help you explore how to use the NPC Toolkit and AI tools to help your business or research team, please reach out to info@npcworldwi.de .
+If you appreciate the work here, [consider supporting NPC Worldwide with a monthly donation](https://buymeacoffee.com/npcworldwide), [buying NPC-WW themed merch](https://enpisi.com/shop), [using and subscribing to Lavanzaro](lavanzaro.com),s or hiring us to help you explore how to use the NPC Toolkit and AI tools to help your business or research team, please reach out to info@npcworldwi.de .
 
 
 ## Installation

{npcsh-1.1.7 → npcsh-1.1.8}/README.md

@@ -43,17 +43,49 @@ and you will enter the NPC shell. Additionally, the pip installation includes th
       ```
 
 
-  - **Search the Web**
+  - **Search**
+    - search the web
     ```bash
-    /search "cal golden bears football schedule" -sp perplexity
+    /search "cerulean city" perplexity
+
     ```
     <p align="center">
-        <img src="https://raw.githubusercontent.com/npc-worldwide/npcsh/main/test_data/search_example.png" alt="example of search results", width=600>
-     </p>
+        <img src="https://raw.githubusercontent.com/npc-worldwide/npcsh/main/test_data/search.gif" alt="example of search results", width=600>
+    </p>
+    
+    - search approved memories
+    ```bash
+    /search query="how to deploy python apps" memory=true
+    ```
+        
+    - search the knowledge graph
+
+    ```bash
+    /search query="user preferences for database" kg=true
+    ```
+        
+    - execute a RAG search across files
+
+    ```bash
+    /search --rag -f ~/docs/api.md,~/docs/config.yaml "authentication setup"
+    ```
+        
+    - brainblast search (searches many keyword combinations)
+
+    ```bash
+    /search query="git commands" brainblast=true
+    ```
+        
+    - web search with specific provider
+
+    ```bash
+    /search query="family vacations" sprovider="perplexity"
+    ```     
 
   - **Computer Use**
+
     ```bash
-    /plonk 'find out the latest news on cnn'
+    /plonk 'find out the latest news on cnn' gemma3:12b ollama
     ```
 
   - **Generate Image**
@@ -65,12 +97,12 @@ and you will enter the NPC shell. Additionally, the pip installation includes th
       </p>
   - **Generate Video**
     ```bash
-    /roll 'generate a video of a hat riding a dog'
+    /roll 'generate a video of a hat riding a dog' veo-3.1-fast-generate-preview  gemini
     ```
-    <!--
+
       <p align="center">
-        <img src="https://raw.githubusercontent.com/npc-worldwide/npcsh/main/test_data/hat_video.mp4" alt="video of a hat riding a dog", width=250>
-      </p> -->
+        <img src="https://raw.githubusercontent.com/NPC-Worldwide/npcsh/main/test_data/hatridingdog.gif" alt="video of a hat riding a dog", width=250>
+      </p> 
 
   - **Serve an NPC Team**
     ```bash
@@ -112,16 +144,13 @@ This architecture enables users to build complex AI workflows while maintaining
 
 Importantly, users can switch easily between the NPCs they are chatting with by typing `/n npc_name` within the NPC shell. Likewise, they can create Jinxs and then use them from within the NPC shell by invoking the jinx name and the arguments required for the Jinx;  `/<jinx_name> arg1 arg2`
 
-# 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,
-    
+# Jinx as macros
+-  activated by invoking `/<jinx_name> ...` in `npcsh`, jinxs 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. 
     - `/alicanto` - Conduct deep research with multiple perspectives, identifying gold insights and cliff warnings. Usage: `/alicanto 'query to be researched' --num-npcs <int> --depth <int>`
     - `/build` - Builds the current npc team to an executable format . Usage: `/build <output[flask,docker,cli,static]> --options`
-    - `/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`
@@ -129,13 +158,11 @@ Importantly, users can switch easily between the NPCs they are chatting with by
     - `/<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.
+    - `/search` - Execute a search command on the web, in your memories, in the knowledge graph, or in documents with rag. Usage: `/search 'search query' --sprovider <provider>` where provider is currently limited to DuckDuckGo, Perplexity, and Exa with more coming soon through litellm. Wikipedia integration ongoing. See above for more search specific examples.
     - `/serve` - Serve an NPC Team server. 
     - `/set` - Set configuration values. 
       - Usage: 
@@ -149,7 +176,6 @@ Importantly, users can switch easily between the NPCs they are chatting with by
       - 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>`
     
@@ -171,24 +197,26 @@ Importantly, users can switch easily between the NPCs they are chatting with by
     '
 
 ## Read the Docs
-To see more about how to use the macros and modes in the NPC Shell, read the docs at [npc-shell.readthedocs.io](https://npc-shell.readthedocs.io/en/latest/)
+To see more about how to use the jinxs and modes in the NPC Shell, read the docs at [npc-shell.readthedocs.io](https://npc-shell.readthedocs.io/en/latest/)
 
 
 ## Inference Capabilities
 - `npcsh` works with local and enterprise LLM providers through its LiteLLM integration, allowing users to run inference from Ollama, LMStudio, vLLM, MLX, OpenAI, Anthropic, Gemini, and Deepseek, making it a versatile tool for both simple commands and sophisticated AI-driven tasks. 
 
 ## NPC Studio
-There is a graphical user interface that makes use of the NPC Toolkit through the NPC Studio. See the source code for NPC Studio [here](https://github.com/npc-worldwide/npc-studio). Download the executables at [our website](https://enpisi.com/npc-studio). For the most up to date version, you can use NPC Studio by invoking it in npcsh 
+There is a graphical user interface that makes use of the NPC Toolkit through the NPC Studio. See the source code for NPC Studio [here](https://github.com/npc-worldwide/npc-studio). Download the executables at [our website](https://enpisi.com/downloads). For the most up to date development version, you can use NPC Studio by invoking it in npcsh 
+
 ```
 /npc-studio
 ```
-which will download and set up and serve the NPC Studio application within your `~/.npcsh` folder. It requires `npm` and `node` to work.
+which will download and set up and serve the NPC Studio application within your `~/.npcsh` folder. It requires `npm` and `node` to work, and of course npcpy !
 
-## Mailing List
+## Mailing List and Community
 Interested 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)!
 
+[Join the discord to discuss ideas for npc tools](https://discord.gg/VvYVT5YC)
 ## Support
-If you appreciate the work here, [consider supporting NPC Worldwide with a monthly donation](https://buymeacoffee.com/npcworldwide), [buying NPC-WW themed merch](https://enpisi.com/shop), or hiring us to help you explore how to use the NPC Toolkit and AI tools to help your business or research team, please reach out to info@npcworldwi.de .
+If you appreciate the work here, [consider supporting NPC Worldwide with a monthly donation](https://buymeacoffee.com/npcworldwide), [buying NPC-WW themed merch](https://enpisi.com/shop), [using and subscribing to Lavanzaro](lavanzaro.com),s or hiring us to help you explore how to use the NPC Toolkit and AI tools to help your business or research team, please reach out to info@npcworldwi.de .
 
 
 ## Installation

{npcsh-1.1.7 → npcsh-1.1.8}/npcsh/corca.py

@@ -1235,68 +1235,98 @@ def create_corca_state_and_mcp_client(conversation_id,
 
     return state
 
-
-def enter_corca_mode(command: str, **kwargs):
-    state: ShellState = kwargs.get('shell_state')
-    command_history: CommandHistory = kwargs.get('command_history')
-
-    if not state or not command_history:
-        return {"output": "Error: Corca mode requires shell state and history.", "messages": kwargs.get('messages', [])}
-
-    all_command_parts = shlex.split(command)
-    parser = argparse.ArgumentParser(prog="/corca", description="Enter Corca MCP-powered mode.")
-    parser.add_argument("--mcp-server-path", type=str, help="Path to an MCP server script.")
-    parser.add_argument("-g", "--global", dest="force_global", action="store_true", help="Force use of global MCP server.")
+def corca_session(
+    command_history: CommandHistory,
+    state: Optional[ShellState] = None,
+    mcp_server_path: Optional[str] = None,
+    force_global: bool = False,
+    initial_command: Optional[str] = None
+) -> Dict[str, Any]:
+    """
+    Clean programmatic entry to Corca mode.
     
-    try:
-        known_args, remaining_args = parser.parse_known_args(all_command_parts[1:])
-    except SystemExit:
-         return {"output": "Invalid arguments for /corca. See /help corca.", "messages": state.messages}
+    Args:
+        command_history: CommandHistory instance
+        state: Optional existing ShellState, will create if None
+        mcp_server_path: Optional explicit path to MCP server
+        force_global: Force use of global MCP server
+        initial_command: Optional command to execute before entering loop
+        
+    Returns:
+        Dict with 'output' and 'messages' keys
+    """
+    # Setup state if not provided
+    if state is None:
+        _, team, default_npc = setup_shell()
+        
+        # Load corca.npc if available
+        project_corca_path = os.path.join('./npc_team/', "corca.npc")
+        global_corca_path = os.path.expanduser('~/.npcsh/npc_team/corca.npc')
+        
+        if os.path.exists(project_corca_path):
+            default_npc = NPC(file=project_corca_path, db_conn=command_history.engine)
+        elif os.path.exists(global_corca_path):
+            default_npc = NPC(file=global_corca_path, db_conn=command_history.engine)
+
+        # Set defaults
+        if default_npc.model is None:
+            default_npc.model = team.model or NPCSH_CHAT_MODEL
+        if default_npc.provider is None:
+            default_npc.provider = team.provider or NPCSH_CHAT_PROVIDER
+
+        from npcsh._state import initial_state
+        state = initial_state
+        state.team = team
+        state.npc = default_npc
+        state.command_history = command_history
 
     print_corca_welcome_message()
     
+    # Resolve MCP server path
     auto_copy_bypass = os.getenv("NPCSH_CORCA_AUTO_COPY_MCP_SERVER", "false").lower() == "true"
-
+    
     resolved_server_path = _resolve_and_copy_mcp_server_path(
-        explicit_path=known_args.mcp_server_path,
+        explicit_path=mcp_server_path,
         current_path=state.current_path,
         team_ctx_mcp_servers=state.team.team_ctx.get('mcp_servers', []) if state.team and hasattr(state.team, 'team_ctx') else None,
         interactive=True,
         auto_copy_bypass=auto_copy_bypass,
-        force_global=known_args.force_global
+        force_global=force_global
     )
 
-    mcp_client = None
+    # Connect to MCP server
     if resolved_server_path:
         try:
             mcp_client = MCPClientNPC()
             if mcp_client.connect_sync(resolved_server_path):
                 state.mcp_client = mcp_client
             else:
-                cprint(f"Failed to connect to MCP server at {resolved_server_path}. Corca mode will have limited agent functionality.", "yellow")
+                cprint(f"Failed to connect to MCP server. Limited functionality.", "yellow")
                 state.mcp_client = None
         except Exception as e:
-            cprint(f"Error connecting to MCP server: {e}. Corca mode will have limited agent functionality.", "red")
+            cprint(f"Error connecting to MCP server: {e}", "red")
             traceback.print_exc()
             state.mcp_client = None
     else:
-        cprint("No MCP server path provided or found. Corca mode will have limited agent functionality.", "yellow")
+        cprint("No MCP server path found. Limited functionality.", "yellow")
         state.mcp_client = None
 
+    # Execute initial command if provided
+    if initial_command:
+        try:
+            state, output = execute_command_corca(initial_command, state, command_history)
+            if not (isinstance(output, dict) and output.get('interrupted')):
+                process_corca_result(initial_command, state, output, command_history)
+        except Exception as e:
+            print(colored(f'Error executing initial command: {e}', "red"))
+
+    # Main loop
     while True:
         try:
-            prompt_npc_name = "npc"
-            if state.npc:
-                prompt_npc_name = state.npc.name
-            
+            prompt_npc_name = state.npc.name if state.npc else "npc"
             prompt_str = f"{colored(os.path.basename(state.current_path), 'blue')}:{prompt_npc_name}🦌> "
             prompt = readline_safe_prompt(prompt_str)
-            
-            if remaining_args:
-                user_input = " ".join(remaining_args)
-                remaining_args = []
-            else:
-                user_input = get_multiline_input(prompt).strip()
+            user_input = get_multiline_input(prompt).strip()
             
             if user_input.lower() in ["exit", "quit", "done"]:
                 break
@@ -1311,11 +1341,7 @@ def enter_corca_mode(command: str, **kwargs):
                     print(colored("\n⚠️  Command interrupted. MCP session maintained.", "yellow"))
                     continue
             
-                process_corca_result(user_input, 
-                            state, 
-                            output, 
-                            command_history, 
-                                )
+                process_corca_result(user_input, state, output, command_history)
             except KeyboardInterrupt:
                 print(colored("\n⚠️  Interrupted. Type 'exit' to quit Corca mode.", "yellow"))
                 continue
@@ -1330,12 +1356,45 @@ def enter_corca_mode(command: str, **kwargs):
             print("\nExiting Corca Mode.")
             break
             
+    # Cleanup
     if state.mcp_client:
         state.mcp_client.disconnect_sync()
         state.mcp_client = None
     
     render_markdown("\n# Exiting Corca Mode")
     return {"output": "", "messages": state.messages}
+def enter_corca_mode(command: str, **kwargs):
+    """Legacy wrapper for command-line entry"""
+    state: ShellState = kwargs.get('shell_state')
+    command_history: CommandHistory = kwargs.get('command_history')
+
+    if not state or not command_history:
+        return {"output": "Error: Corca mode requires shell state and history.", "messages": kwargs.get('messages', [])}
+
+    # Parse command arguments
+    all_command_parts = shlex.split(command)
+    parser = argparse.ArgumentParser(prog="/corca", description="Enter Corca MCP-powered mode.")
+    parser.add_argument("--mcp-server-path", type=str, help="Path to an MCP server script.")
+    parser.add_argument("-g", "--global", dest="force_global", action="store_true", help="Force use of global MCP server.")
+    
+    try:
+        known_args, remaining_args = parser.parse_known_args(all_command_parts[1:])
+    except SystemExit:
+         return {"output": "Invalid arguments for /corca. See /help corca.", "messages": state.messages}
+
+    # Get initial command from remaining args
+    initial_command = " ".join(remaining_args) if remaining_args else None
+
+    # Call the clean entry point
+    return corca_session(
+        command_history=command_history,
+        state=state,
+        mcp_server_path=known_args.mcp_server_path,
+        force_global=known_args.force_global,
+        initial_command=initial_command
+    )
+
+
 def main():
     parser = argparse.ArgumentParser(description="Corca - An MCP-powered npcsh shell.")
     parser.add_argument("--mcp-server-path", type=str, help="Path to an MCP server script to connect to.")

npcsh-1.1.8/npcsh/npc_team/jinxs/modes/corca.jinx

@@ -0,0 +1,28 @@
+jinx_name: "corca"
+description: "Enter the Corca MCP-powered agentic shell"
+inputs:
+  - mcp_server_path: '~/.npcsh/npc_team/mcp_server.py'
+  - force_global: false
+  - initial_command: null
+steps:
+  - name: "enter_corca"
+    engine: "python"
+    code: |
+      from npcsh._state import setup_shell 
+      from npcsh.corca import corca_session
+      
+      mcp_server_path = context.get('mcp_server_path')
+      force_global = context.get('force_global', False)
+      initial_command = context.get('initial_command')
+      
+      command_history, _, _ = setup_shell()
+      
+      result = corca_session(
+          command_history=command_history,
+          mcp_server_path=mcp_server_path,
+          force_global=force_global,
+          initial_command=initial_command
+      )
+      
+      context['output'] = result.get('output', 'Exited Corca mode.')
+      context['messages'] = result.get('messages', [])

{npcsh-1.1.7 → npcsh-1.1.8}/npcsh/npc_team/jinxs/modes/plonk.jinx

@@ -30,10 +30,6 @@ steps:
       if not vision_provider and current_npc and current_npc.provider:
           vision_provider = current_npc.provider
       
-      # Final fallbacks (these would ideally come from npcsh._state config)
-      if not vision_model: vision_model = "gemini-1.5-pro-vision" # Example default
-      if not vision_provider: vision_provider = "gemini" # Example default
-
       try:
           summary_data = execute_plonk_command(
               request=task_description,

{npcsh-1.1.7 → npcsh-1.1.8}/npcsh/npc_team/jinxs/utils/ots.jinx

@@ -38,10 +38,10 @@ steps:
               print(f"📸 Screenshot captured: {screenshot_info.get('filename', os.path.basename(screenshot_info['file_path']))}")
 
       if not vision_model:
-          vision_model = getattr(current_npc, 'model', 'gpt-4o-mini')
+          vision_model = getattr(current_npc, 'model', 'gemma3:4b')
       
       if not vision_provider:
-          vision_provider = getattr(current_npc, 'provider', 'openai')
+          vision_provider = getattr(current_npc, 'provider', 'ollama')
 
       response_data = get_llm_response(
           prompt=user_prompt,

{npcsh-1.1.7 → npcsh-1.1.8}/npcsh/npc_team/jinxs/utils/roll.jinx

@@ -2,12 +2,12 @@ jinx_name: "roll"
 description: "Generate a video from a text prompt."
 inputs:
   - prompt: "" # Required text prompt for video generation.
+  - vgmodel: "" # Video generation model to use. Defaults to NPCSH_VIDEO_GEN_MODEL or NPC's model.
+  - vgprovider: "" # Video generation provider to use. Defaults to NPCSH_VIDEO_GEN_PROVIDER or NPC's provider.
   - num_frames: 125 # Number of frames for the video.
   - width: 256 # Width of the video.
   - height: 256 # Height of the video.
   - output_path: "output.mp4" # Output file path for the video.
-  - vgmodel: "" # Video generation model to use. Defaults to NPCSH_VIDEO_GEN_MODEL or NPC's model.
-  - vgprovider: "" # Video generation provider to use. Defaults to NPCSH_VIDEO_GEN_PROVIDER or NPC's provider.
 steps:
   - name: "generate_video"
     engine: "python"
@@ -38,8 +38,10 @@ steps:
           video_gen_provider = current_npc.provider
       
       # Final fallbacks (these would ideally come from npcsh._state config)
-      if not video_gen_model: video_gen_model = "stable-video-diffusion" # Example default
-      if not video_gen_provider: video_gen_provider = "diffusers" # Example default
+      if not video_gen_model: 
+            video_gen_model = "stable-video-diffusion" # Example default
+      if not video_gen_provider: 
+            video_gen_provider = "diffusers" # Example default
 
       try:
           result = gen_video(

{npcsh-1.1.7 → npcsh-1.1.8}/npcsh/npc_team/jinxs/utils/search.jinx

@@ -9,6 +9,7 @@ description: >
     /search --brainblast <query>            (Advanced history search)
 inputs:
   - query: ""
+  - sprovider: ""
   - memory: false
   - kg: false
   - rag: false
@@ -16,7 +17,6 @@ inputs:
   - file_paths: ""
   - history_db_path: "~/npcsh_history.db"
   - vector_db_path: "~/npcsh_chroma.db"
-  - sprovider: ""
   - emodel: ""
   - eprovider: ""
 steps:

{npcsh-1.1.7 → npcsh-1.1.8}/npcsh/npcsh.py

@@ -140,23 +140,24 @@ def run_repl(command_history: CommandHistory, initial_state: ShellState, router)
 
     while True:
         try:
-            if len(state.messages) > 20:
-                planning_state = {
-                    "goal": "ongoing npcsh session", 
-                    "facts": [f"Working in {state.current_path}", f"Current mode: {state.current_mode}"], 
-                    "successes": [], 
-                    "mistakes": [],
-                    "todos": [],
-                    "constraints": ["Follow user requests", "Use appropriate mode for tasks"]
-                }
-                compressed_state = state.npc.compress_planning_state(planning_state)
-                state.messages = [{"role": "system", "content": f"Session context: {compressed_state}"}]
-
-            try:
-                completer = make_completer(state, router)
-                readline.set_completer(completer)
-            except:
-                pass
+            if state.messages is not None:
+                if len(state.messages) > 20:
+                    planning_state = {
+                        "goal": "ongoing npcsh session", 
+                        "facts": [f"Working in {state.current_path}", f"Current mode: {state.current_mode}"], 
+                        "successes": [], 
+                        "mistakes": [],
+                        "todos": [],
+                        "constraints": ["Follow user requests", "Use appropriate mode for tasks"]
+                    }
+                    compressed_state = state.npc.compress_planning_state(planning_state)
+                    state.messages = [{"role": "system", "content": f"Session context: {compressed_state}"}]
+
+                try:
+                    completer = make_completer(state, router)
+                    readline.set_completer(completer)
+                except:
+                    pass
 
             display_model = state.chat_model
             if isinstance(state.npc, NPC) and state.npc.model:

{npcsh-1.1.7 → npcsh-1.1.8}/npcsh.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: npcsh
-Version: 1.1.7
+Version: 1.1.8
 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
@@ -143,17 +143,49 @@ and you will enter the NPC shell. Additionally, the pip installation includes th
       ```
 
 
-  - **Search the Web**
+  - **Search**
+    - search the web
     ```bash
-    /search "cal golden bears football schedule" -sp perplexity
+    /search "cerulean city" perplexity
+
     ```
     <p align="center">
-        <img src="https://raw.githubusercontent.com/npc-worldwide/npcsh/main/test_data/search_example.png" alt="example of search results", width=600>
-     </p>
+        <img src="https://raw.githubusercontent.com/npc-worldwide/npcsh/main/test_data/search.gif" alt="example of search results", width=600>
+    </p>
+    
+    - search approved memories
+    ```bash
+    /search query="how to deploy python apps" memory=true
+    ```
+        
+    - search the knowledge graph
+
+    ```bash
+    /search query="user preferences for database" kg=true
+    ```
+        
+    - execute a RAG search across files
+
+    ```bash
+    /search --rag -f ~/docs/api.md,~/docs/config.yaml "authentication setup"
+    ```
+        
+    - brainblast search (searches many keyword combinations)
+
+    ```bash
+    /search query="git commands" brainblast=true
+    ```
+        
+    - web search with specific provider
+
+    ```bash
+    /search query="family vacations" sprovider="perplexity"
+    ```     
 
   - **Computer Use**
+
     ```bash
-    /plonk 'find out the latest news on cnn'
+    /plonk 'find out the latest news on cnn' gemma3:12b ollama
     ```
 
   - **Generate Image**
@@ -165,12 +197,12 @@ and you will enter the NPC shell. Additionally, the pip installation includes th
       </p>
   - **Generate Video**
     ```bash
-    /roll 'generate a video of a hat riding a dog'
+    /roll 'generate a video of a hat riding a dog' veo-3.1-fast-generate-preview  gemini
     ```
-    <!--
+
       <p align="center">
-        <img src="https://raw.githubusercontent.com/npc-worldwide/npcsh/main/test_data/hat_video.mp4" alt="video of a hat riding a dog", width=250>
-      </p> -->
+        <img src="https://raw.githubusercontent.com/NPC-Worldwide/npcsh/main/test_data/hatridingdog.gif" alt="video of a hat riding a dog", width=250>
+      </p> 
 
   - **Serve an NPC Team**
     ```bash
@@ -212,16 +244,13 @@ This architecture enables users to build complex AI workflows while maintaining
 
 Importantly, users can switch easily between the NPCs they are chatting with by typing `/n npc_name` within the NPC shell. Likewise, they can create Jinxs and then use them from within the NPC shell by invoking the jinx name and the arguments required for the Jinx;  `/<jinx_name> arg1 arg2`
 
-# 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,
-    
+# Jinx as macros
+-  activated by invoking `/<jinx_name> ...` in `npcsh`, jinxs 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. 
     - `/alicanto` - Conduct deep research with multiple perspectives, identifying gold insights and cliff warnings. Usage: `/alicanto 'query to be researched' --num-npcs <int> --depth <int>`
     - `/build` - Builds the current npc team to an executable format . Usage: `/build <output[flask,docker,cli,static]> --options`
-    - `/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`
@@ -229,13 +258,11 @@ Importantly, users can switch easily between the NPCs they are chatting with by
     - `/<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.
+    - `/search` - Execute a search command on the web, in your memories, in the knowledge graph, or in documents with rag. Usage: `/search 'search query' --sprovider <provider>` where provider is currently limited to DuckDuckGo, Perplexity, and Exa with more coming soon through litellm. Wikipedia integration ongoing. See above for more search specific examples.
     - `/serve` - Serve an NPC Team server. 
     - `/set` - Set configuration values. 
       - Usage: 
@@ -249,7 +276,6 @@ Importantly, users can switch easily between the NPCs they are chatting with by
       - 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>`
     
@@ -271,24 +297,26 @@ Importantly, users can switch easily between the NPCs they are chatting with by
     '
 
 ## Read the Docs
-To see more about how to use the macros and modes in the NPC Shell, read the docs at [npc-shell.readthedocs.io](https://npc-shell.readthedocs.io/en/latest/)
+To see more about how to use the jinxs and modes in the NPC Shell, read the docs at [npc-shell.readthedocs.io](https://npc-shell.readthedocs.io/en/latest/)
 
 
 ## Inference Capabilities
 - `npcsh` works with local and enterprise LLM providers through its LiteLLM integration, allowing users to run inference from Ollama, LMStudio, vLLM, MLX, OpenAI, Anthropic, Gemini, and Deepseek, making it a versatile tool for both simple commands and sophisticated AI-driven tasks. 
 
 ## NPC Studio
-There is a graphical user interface that makes use of the NPC Toolkit through the NPC Studio. See the source code for NPC Studio [here](https://github.com/npc-worldwide/npc-studio). Download the executables at [our website](https://enpisi.com/npc-studio). For the most up to date version, you can use NPC Studio by invoking it in npcsh 
+There is a graphical user interface that makes use of the NPC Toolkit through the NPC Studio. See the source code for NPC Studio [here](https://github.com/npc-worldwide/npc-studio). Download the executables at [our website](https://enpisi.com/downloads). For the most up to date development version, you can use NPC Studio by invoking it in npcsh 
+
 ```
 /npc-studio
 ```
-which will download and set up and serve the NPC Studio application within your `~/.npcsh` folder. It requires `npm` and `node` to work.
+which will download and set up and serve the NPC Studio application within your `~/.npcsh` folder. It requires `npm` and `node` to work, and of course npcpy !
 
-## Mailing List
+## Mailing List and Community
 Interested 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)!
 
+[Join the discord to discuss ideas for npc tools](https://discord.gg/VvYVT5YC)
 ## Support
-If you appreciate the work here, [consider supporting NPC Worldwide with a monthly donation](https://buymeacoffee.com/npcworldwide), [buying NPC-WW themed merch](https://enpisi.com/shop), or hiring us to help you explore how to use the NPC Toolkit and AI tools to help your business or research team, please reach out to info@npcworldwi.de .
+If you appreciate the work here, [consider supporting NPC Worldwide with a monthly donation](https://buymeacoffee.com/npcworldwide), [buying NPC-WW themed merch](https://enpisi.com/shop), [using and subscribing to Lavanzaro](lavanzaro.com),s or hiring us to help you explore how to use the NPC Toolkit and AI tools to help your business or research team, please reach out to info@npcworldwi.de .
 
 
 ## Installation

{npcsh-1.1.7 → npcsh-1.1.8}/setup.py

@@ -78,7 +78,7 @@ extra_files = package_files("npcsh/npc_team/")
 
 setup(
     name="npcsh",
-    version="1.1.7",
+    version="1.1.8",
     packages=find_packages(exclude=["tests*"]),
     install_requires=base_requirements,  # Only install base requirements by default
     extras_require={

npcsh-1.1.7/npcsh/npc_team/jinxs/modes/corca.jinx

@@ -1,28 +0,0 @@
-jinx_name: "corca"
-description: "Enter the Corca MCP-powered agentic shell. Usage: /corca [--mcp-server-path path]"
-inputs:
-  - command: "/corca" # The full command string, e.g., "/corca --mcp-server-path /tmp/mcp"
-steps:
-  - name: "enter_corca"
-    engine: "python"
-    code: |
-      # Assume npcsh._state and enter_corca_mode are accessible in the environment
-
-      from npcsh._state import initial_state, setup_shell 
-      from npcsh.corca import enter_corca_mode
-
-
-      full_command_str = context.get('command')
-      output_messages = context.get('messages', [])
-      
-      command_history, team, default_npc = setup_shell()
-      
-      result = enter_corca_mode(
-          command=full_command_str, 
-          command_history=command_history, 
-          shell_state=initial_state,
-          **context # Pass all context as kwargs to enter_corca_mode as it expects
-      )
-      
-      context['output'] = result.get('output', 'Entered Corca mode.')
-      context['messages'] = result.get('messages', output_messages)