npcsh 0.3.24__tar.gz → 0.3.26__tar.gz

{npcsh-0.3.24/npcsh.egg-info → npcsh-0.3.26}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: npcsh
-Version: 0.3.24
+Version: 0.3.26
 Summary: npcsh is a command line tool for integrating LLMs into everyday workflows and for orchestrating teams of NPCs.
 Home-page: https://github.com/cagostino/npcsh
 Author: Christopher Agostino
@@ -27,7 +27,6 @@ Requires-Dist: opencv-python
 Requires-Dist: librosa
 Requires-Dist: openai
 Requires-Dist: jinja2
-Requires-Dist: pyautogui
 Requires-Dist: pandas
 Requires-Dist: matplotlib
 Requires-Dist: IPython
@@ -37,14 +36,11 @@ Requires-Dist: markdown
 Requires-Dist: PyYAML
 Requires-Dist: langchain
 Requires-Dist: langchain_community
-Requires-Dist: openai-whisper
-Requires-Dist: pyaudio
+Requires-Dist: pyautogui
 Requires-Dist: pygments
 Requires-Dist: pyttsx3
 Requires-Dist: kuzu
 Requires-Dist: chromadb
-Requires-Dist: gtts
-Requires-Dist: playsound==1.2.2
 Requires-Dist: termcolor
 Requires-Dist: colorama
 Requires-Dist: python-dotenv
@@ -59,6 +55,7 @@ Dynamic: classifier
 Dynamic: description
 Dynamic: description-content-type
 Dynamic: home-page
+Dynamic: license-file
 Dynamic: requires-dist
 Dynamic: requires-python
 Dynamic: summary
@@ -71,7 +68,7 @@ Dynamic: summary
 # npcsh
 
 
-- `npcsh` is a python-based command-line tool designed to integrate Large Language Models (LLMs) and Agents into one's daily workflow by making them available and easily configurable through the command line shell.
+- `npcsh` is a python-based AI Agent framework designed to integrate Large Language Models (LLMs) and Agents into one's daily workflow by making them available and easily configurable through a command line shell as well as an extensible python library.
 
 - **Smart Interpreter**: `npcsh` leverages the power of LLMs to understand your natural language commands and questions, executing tasks, answering queries, and providing relevant information from local files and the web.
 
@@ -82,10 +79,9 @@ Dynamic: summary
 
 * **Extensible with Python:**  `npcsh`'s python package provides useful functions for interacting with LLMs, including explicit coverage for popular providers like ollama, anthropic, openai, gemini, deepseek, and openai-like providers. Each macro has a corresponding function and these can be used in python scripts. `npcsh`'s functions are purpose-built to simplify NPC interactions but NPCs are not required for them to work if you don't see the need.
 
-* **Simple, Powerful CLI:**  Use the `npc` CLI commands to set up a flask server so you can expose your NPC team for use as a backend service. You can also use the `npc` CLI to run SQL models defined in your project, execute assembly lines, and verify the integrity of your NPC team's interrelations. `npcsh`'s NPCs take advantage of jinja templating to reference other NPCs and tools in their properties, and the `npc` CLI can be used to verify these references.
-
-* **Shell Strengths:** Execute bash commands directly. Use your favorite command-line tools like VIM, Emacs, ipython, sqlite3, git. Pipe the output of these commands to LLMs or pass LLM results to bash commands.
+* **Simple, Powerful CLI:**  Use the `npc` CLI commands to run `npcsh` macros or commands from one's regular shell. Set up a flask server so you can expose your NPC team for use as a backend service. You can also use the `npc` CLI to run SQL models defined in your project, execute assembly lines, and verify the integrity of your NPC team's interrelations. `npcsh`'s NPCs take advantage of jinja templating to reference other NPCs and tools in their properties, and the `npc` CLI can be used to verify these references.
 
+* **Powerful Tool integrations:** `npcsh` has built-in tools for users to have agents execute code, analyze data, generate images, search the web, and more. Tools can be defined in YAML files as part of project-specific `npc_team`s or in the global `~/.npcsh/npc_team` directory or simply in python scripts. Once compiled, the tools can be used as macros in the `npc` cli as well as `/{tool_name}` commands in the `npcsh` shell.
 
 
 Interested to stay in the loop and to hear the latest and greatest about `npcsh` ? Be sure to sign up for the [npcsh newsletter](https://forms.gle/n1NzQmwjsV4xv1B2A)!
@@ -112,6 +108,335 @@ Users can take advantage of `npcsh` through its custom shell or through a comman
 | Voice Chat    | npc whisper 'npc_name'   | /whisper   |
 
 
+## Python Examples
+Integrate npcsh into your Python projects for additional flexibility. Below are a few examples of how to use the library programmatically.
+
+
+
+### Example 1: Creating and Using an NPC
+This example shows how to create and initialize an NPC and use it to answer a question.
+```bash
+import sqlite3
+from npcsh.npc_compiler import NPC
+
+# Set up database connection
+db_path = '~/npcsh_history.db'
+conn = sqlite3.connect(db_path)
+
+# Load NPC from a file
+npc = NPC(
+          name='Simon Bolivar',
+          db_conn=conn,
+          primary_directive='Liberate South America from the Spanish Royalists.',
+          model='gpt-4o-mini',
+          provider='openai',
+          )
+
+response = npc.get_llm_response("What is the most important territory to retain in the Andes mountains?")
+print(response['response'])
+```
+```bash
+'The most important territory to retain in the Andes mountains for the cause of liberation in South America would be the region of Quito in present-day Ecuador. This area is strategically significant due to its location and access to key trade routes. It also acts as a vital link between the northern and southern parts of the continent, influencing both military movements and the morale of the independence struggle. Retaining control over Quito would bolster efforts to unite various factions in the fight against Spanish colonial rule across the Andean states.'
+```
+### Example 2: Using an NPC to Analyze Data
+This example shows how to use an NPC to perform data analysis on a DataFrame using LLM commands.
+```bash
+from npcsh.npc_compiler import NPC
+import sqlite3
+import os
+# Set up database connection
+db_path = '~/npcsh_history.db'
+conn = sqlite3.connect(os.path.expanduser(db_path))
+
+# make a table to put into npcsh_history.db or change this example to use an existing table in a database you have
+import pandas as pd
+data = {
+        'customer_feedback': ['The product is great!', 'The service was terrible.', 'I love the new feature.'],
+        'customer_id': [1, 2, 3],
+        'customer_rating': [5, 1, 3],
+        'timestamp': ['2022-01-01', '2022-01-02', '2022-01-03']
+        }
+
+
+df = pd.DataFrame(data)
+df.to_sql('customer_feedback', conn, if_exists='replace', index=False)
+
+
+npc = NPC(
+          name='Felix',
+          db_conn=conn,
+          primary_directive='Analyze customer feedback for sentiment.',
+          model='gpt-4o-mini',
+          provider='openai',
+          )
+response = npc.analyze_db_data('Provide a detailed report on the data contained in the `customer_feedback` table?')
+
+
+```
+
+
+### Example 3: Creating and Using a Tool
+You can define a tool and execute it from within your Python script.
+Here we'll create a tool that will take in a pdf file, extract the text, and then answer a user request about the text.
+
+```bash
+from npcsh.npc_compiler import Tool, NPC
+import sqlite3
+import os
+
+from jinja2 import Environment, FileSystemLoader
+
+# Create a proper Jinja environment
+jinja_env = Environment(loader=FileSystemLoader('.'))
+
+
+tool_data = {
+    "tool_name": "pdf_analyzer",
+    "inputs": ["request", "file"],
+    "steps": [{  # Make this a list with one dict inside
+        "engine": "python",
+        "code": """
+try:
+    import fitz  # PyMuPDF
+
+    shared_context = {}
+    shared_context['inputs'] = '{{request}}'
+
+    pdf_path = '{{file}}'
+
+
+
+    # Open the PDF
+    doc = fitz.open(pdf_path)
+    text = ""
+
+    # Extract text from each page
+    for page_num in range(len(doc)):
+        page = doc[page_num]
+        text += page.get_text()
+
+    # Close the document
+    doc.close()
+
+    print(f"Extracted text length: {len(text)}")
+    if len(text) > 100:
+        print(f"First 100 characters: {text[:100]}...")
+
+    shared_context['extracted_text'] = text
+    print("Text extraction completed successfully")
+
+except Exception as e:
+    error_msg = f"Error processing PDF: {str(e)}"
+    print(error_msg)
+    shared_context['extracted_text'] = f"Error: {error_msg}"
+"""
+    },
+     {
+        "engine": "natural",
+        "code": """
+{% if shared_context and shared_context.extracted_text %}
+{% if shared_context.extracted_text.startswith('Error:') %}
+{{ shared_context.extracted_text }}
+{% else %}
+Here is the text extracted from the PDF:
+
+{{ shared_context.extracted_text }}
+
+Please provide a response to user request: {{ request }} using the information extracted above.
+{% endif %}
+{% else %}
+Error: No text was extracted from the PDF.
+{% endif %}
+"""
+    },]
+    }
+
+# Instantiate the tool
+tool = Tool(tool_data)
+
+# Create an NPC instance
+npc = NPC(
+    name='starlana',
+    primary_directive='Analyze text from Astrophysics papers with a keen attention to theoretical machinations and mechanisms.',
+    model = 'llama3.2',
+    provider='ollama',
+    db_conn=sqlite3.connect(os.path.expanduser('~/npcsh_database.db'))
+)
+
+# Define input values dictionary
+input_values = {
+    "request": "what is the point of the yuan and narayanan work?",
+    "file": os.path.abspath("test_data/yuan2004.pdf")
+}
+
+print(f"Attempting to read file: {input_values['file']}")
+print(f"File exists: {os.path.exists(input_values['file'])}")
+
+# Execute the tool
+output = tool.execute(input_values, npc.tools_dict, jinja_env, 'Sample Command',model=npc.model, provider=npc.provider,  npc=npc)
+
+print('Tool Output:', output)
+```
+
+### Example 4: Orchestrating a team
+
+
+
+```python
+import pandas as pd
+import numpy as np
+import os
+from npcsh.npc_compiler import NPC, NPCTeam, Tool
+
+
+# Create test data and save to CSV
+def create_test_data(filepath="sales_data.csv"):
+    sales_data = pd.DataFrame(
+        {
+            "date": pd.date_range(start="2024-01-01", periods=90),
+            "revenue": np.random.normal(10000, 2000, 90),
+            "customer_count": np.random.poisson(100, 90),
+            "avg_ticket": np.random.normal(100, 20, 90),
+            "region": np.random.choice(["North", "South", "East", "West"], 90),
+            "channel": np.random.choice(["Online", "Store", "Mobile"], 90),
+        }
+    )
+
+    # Add patterns to make data more realistic
+    sales_data["revenue"] *= 1 + 0.3 * np.sin(
+        np.pi * np.arange(90) / 30
+    )  # Seasonal pattern
+    sales_data.loc[sales_data["channel"] == "Mobile", "revenue"] *= 1.1  # Mobile growth
+    sales_data.loc[
+        sales_data["channel"] == "Online", "customer_count"
+    ] *= 1.2  # Online customer growth
+
+    sales_data.to_csv(filepath, index=False)
+    return filepath, sales_data
+
+
+code_execution_tool = Tool(
+    {
+        "tool_name": "execute_code",
+        "description": """Executes a Python code block with access to pandas,
+                          numpy, and matplotlib.
+                          Results should be stored in the 'results' dict to be returned.
+                          The only input should be a single code block with \n characters included.
+                          The code block must use only the  libraries or methods contained withen the
+                            pandas, numpy, and matplotlib libraries or using builtin methods.
+                          do not include any json formatting or markdown formatting.
+
+                          When generating your script, the final output must be encoded in a variable
+                          named "output". e.g.
+
+                          output  = some_analysis_function(inputs, derived_data_from_inputs)
+                            Adapt accordingly based on the scope of the analysis
+
+                          """,
+        "inputs": ["script"],
+        "steps": [
+            {
+                "engine": "python",
+                "code": """{{script}}""",
+            }
+        ],
+    }
+)
+
+# Analytics team definition
+analytics_team = [
+    {
+        "name": "analyst",
+        "primary_directive": "You analyze sales performance data, focusing on revenue trends, customer behavior metrics, and market indicators. Your expertise is in extracting actionable insights from complex datasets.",
+        "model": "gpt-4o-mini",
+        "provider": "openai",
+        "tools": [code_execution_tool],  # Only the code execution tool
+    },
+    {
+        "name": "researcher",
+        "primary_directive": "You specialize in causal analysis and experimental design. Given data insights, you determine what factors drive observed patterns and design tests to validate hypotheses.",
+        "model": "gpt-4o-mini",
+        "provider": "openai",
+        "tools": [code_execution_tool],  # Only the code execution tool
+    },
+    {
+        "name": "engineer",
+        "primary_directive": "You implement data pipelines and optimize data processing. When given analysis requirements, you create efficient workflows to automate insights generation.",
+        "model": "gpt-4o-mini",
+        "provider": "openai",
+        "tools": [code_execution_tool],  # Only the code execution tool
+    },
+]
+
+
+def create_analytics_team():
+    # Initialize NPCs with just the code execution tool
+    npcs = []
+    for npc_data in analytics_team:
+        npc = NPC(
+            name=npc_data["name"],
+            primary_directive=npc_data["primary_directive"],
+            model=npc_data["model"],
+            provider=npc_data["provider"],
+            tools=[code_execution_tool],  # Only code execution tool
+        )
+        npcs.append(npc)
+
+    # Create coordinator with just code execution tool
+    coordinator = NPC(
+        name="coordinator",
+        primary_directive="You coordinate the analytics team, ensuring each specialist contributes their expertise effectively. You synthesize insights and manage the workflow.",
+        model="gpt-4o-mini",
+        provider="openai",
+        tools=[code_execution_tool],  # Only code execution tool
+    )
+
+    # Create team
+    team = NPCTeam(npcs=npcs, foreman=coordinator)
+    return team
+
+
+def main():
+    # Create and save test data
+    data_path, sales_data = create_test_data()
+
+    # Initialize team
+    team = create_analytics_team()
+
+    # Run analysis - updated prompt to reflect code execution approach
+    results = team.orchestrate(
+        f"""
+    Analyze the sales data at {data_path} to:
+    1. Identify key performance drivers
+    2. Determine if mobile channel growth is significant
+    3. Recommend tests to validate growth hypotheses
+
+    Here is a header for the data file at {data_path}:
+    {sales_data.head()}
+
+    When working with dates, ensure that date columns are converted from raw strings. e.g. use the pd.to_datetime function.
+
+
+    When working with potentially messy data, handle null values by using nan versions of numpy functions or
+    by filtering them with a mask .
+
+    Use Python code execution to perform the analysis - load the data and perform statistical analysis directly.
+    """
+    )
+
+    print(results)
+
+    # Cleanup
+    os.remove(data_path)
+
+
+if __name__ == "__main__":
+    main()
+
+```
+
+
+
 ## Star History
 
 [![Star History Chart](https://api.star-history.com/svg?repos=cagostino/npcsh&type=Date)](https://star-history.com/#cagostino/npcsh&Date)
@@ -137,7 +462,10 @@ ollama pull llava:7b
 ollama pull nomic-embed-text
 pip install npcsh
 ```
-
+If you'd like to install the abilities to use STT and TTS, additionall install the following
+```
+pip install openai-whisper pyaudio gtts playsound
+```
 
 
 
@@ -153,7 +481,7 @@ ollama pull llava:7b
 ollama pull nomic-embed-text
 pip install npcsh
 ```
-### Widows Install
+### Windows Install
 
 Download and install ollama exe.
 
@@ -799,6 +1127,7 @@ Citation Links: ['https://en.wikipedia.org/wiki/List_of_presidents_of_the_United
 
 Bash:
 
+```bash
 (npcsh) caug@pop-os:~/npcww/npcsh$ npc search 'simon bolivar' -sp perplexity
 Loaded .env file from /home/caug/npcww/npcsh
 urls ['https://en.wikipedia.org/wiki/Sim%C3%B3n_Bol%C3%ADvar', 'https://www.britannica.com/biography/Simon-Bolivar', 'https://en.wikipedia.org/wiki/File:Sim%C3%B3n_Bol%C3%ADvar_2.jpg', 'https://www.historytoday.com/archive/simon-bolivar-and-spanish-revolutions', 'https://kids.britannica.com/kids/article/Sim%C3%B3n-Bol%C3%ADvar/352872']
@@ -1069,9 +1398,10 @@ Tools are defined as YAMLs with `.tool` extension within the npc_team/tools dire
 Here is an example of a tool file:
 ```yaml
 tool_name: "screen_capture_analysis_tool"
+description: Captures the whole screen and sends the image for analysis
 inputs:
   - "prompt"
-preprocess:
+steps:
   - engine: "python"
     code: |
       # Capture the screen
@@ -1079,30 +1409,22 @@ preprocess:
       import datetime
       import os
       from PIL import Image
-      from npcsh.image import analyze_image_base
-
-      # Generate filename
-      filename = f"screenshot_{datetime.datetime.now().strftime('%Y%m%d_%H%M%S')}.png"
-      screenshot = pyautogui.screenshot()
-      screenshot.save(filename)
-      print(f"Screenshot saved as {filename}")
-
-      # Load image
-      image = Image.open(filename)
-
-      # Full file path
-      file_path = os.path.abspath('./'+filename)
-      # Analyze the image
-
-      llm_output = analyze_image_base(inputs['prompt']+ '\n\n attached is a screenshot of my screen currently.', file_path, filename, npc=npc)
-prompt:
-  engine: "natural"
-  code: ""
-postprocess:
-  - engine: "natural"
-    code: |
-      Screenshot captured and saved as {{ filename }}.
-      Analysis Result: {{ llm_output }}
+      import time
+      from npcsh.image import analyze_image_base, capture_screenshot
+
+      out = capture_screenshot(npc = npc, full = True)
+
+      llm_response = analyze_image_base( '{{prompt}}' + "\n\nAttached is a screenshot of my screen currently. Please use this to evaluate the situation. If the user asked for you to explain what's on their screen or something similar, they are referring to the details contained within the attached image. You do not need to actually view their screen. You do not need to mention that you cannot view or interpret images directly. You only need to answer the user's request based on the attached screenshot!",
+                                        out['file_path'],
+                                        out['filename'],
+                                        npc=npc,
+                                        **out['model_kwargs'])
+      # To this:
+      if isinstance(llm_response, dict):
+          llm_response = llm_response.get('response', 'No response from image analysis')
+      else:
+          llm_response = 'No response from image analysis'
+
 ```
 
 
@@ -1415,164 +1737,6 @@ results = runner.execute_pipeline()
 Note, in the future we will aim to separate compilation and running so that we will have a compilation step that is more like a jinja rendering of the relevant information so that it can be more easily audited.
 
 
-## Python Examples
-Integrate npcsh into your Python projects for additional flexibility. Below are a few examples of how to use the library programmatically.
-
-
-
-### Example 1: Creating and Using an NPC
-This example shows how to create and initialize an NPC and use it to answer a question.
-```bash
-import sqlite3
-from npcsh.npc_compiler import NPC
-
-# Set up database connection
-db_path = '~/npcsh_history.db'
-conn = sqlite3.connect(db_path)
-
-# Load NPC from a file
-npc = NPC(db_conn=conn,
-          name='Simon Bolivar',
-          primary_directive='Liberate South America from the Spanish Royalists.',
-          model='gpt-4o-mini',
-          provider='openai',
-          )
-
-response = npc.get_llm_response("What is the most important territory to retain in the Andes mountains?")
-print(response['response'])
-```
-```bash
-'The most important territory to retain in the Andes mountains for the cause of liberation in South America would be the region of Quito in present-day Ecuador. This area is strategically significant due to its location and access to key trade routes. It also acts as a vital link between the northern and southern parts of the continent, influencing both military movements and the morale of the independence struggle. Retaining control over Quito would bolster efforts to unite various factions in the fight against Spanish colonial rule across the Andean states.'
-```
-### Example 2: Using an NPC to Analyze Data
-This example shows how to use an NPC to perform data analysis on a DataFrame using LLM commands.
-```bash
-from npcsh.npc_compiler import NPC
-import sqlite3
-import os
-# Set up database connection
-db_path = '~/npcsh_history.db'
-conn = sqlite3.connect(os.path.expanduser(db_path))
-
-# make a table to put into npcsh_history.db or change this example to use an existing table in a database you have
-import pandas as pd
-data = {
-        'customer_feedback': ['The product is great!', 'The service was terrible.', 'I love the new feature.'],
-        'customer_id': [1, 2, 3],
-        'customer_rating': [5, 1, 3],
-        'timestamp': ['2022-01-01', '2022-01-02', '2022-01-03']
-        }
-
-
-df = pd.DataFrame(data)
-df.to_sql('customer_feedback', conn, if_exists='replace', index=False)
-
-
-npc = NPC(db_conn=conn,
-          name='Felix',
-          primary_directive='Analyze customer feedback for sentiment.',
-          model='llama3.2',
-          provider='ollama',
-          )
-response = npc.analyze_db_data('Provide a detailed report on the data contained in the `customer_feedback` table?')
-
-
-```
-
-
-### Example 3: Creating and Using a Tool
-You can define a tool and execute it from within your Python script.
-Here we'll create a tool that will take in a pdf file, extract the text, and then answer a user request about the text.
-
-```bash
-from npcsh.npc_compiler import Tool, NPC
-import sqlite3
-import os
-
-tool_data = {
-    "tool_name": "pdf_analyzer",
-    "inputs": ["request", "file"],
-    "steps": [{  # Make this a list with one dict inside
-        "engine": "python",
-        "code": """
-try:
-    import fitz  # PyMuPDF
-
-    shared_context = {}
-    shared_context['inputs'] = inputs
-
-    pdf_path = inputs['file']
-    print(f"Processing PDF file: {pdf_path}")
-
-    # Open the PDF
-    doc = fitz.open(pdf_path)
-    text = ""
-
-    # Extract text from each page
-    for page_num in range(len(doc)):
-        page = doc[page_num]
-        text += page.get_text()
-
-    # Close the document
-    doc.close()
-
-    print(f"Extracted text length: {len(text)}")
-    if len(text) > 100:
-        print(f"First 100 characters: {text[:100]}...")
-
-    shared_context['extracted_text'] = text
-    print("Text extraction completed successfully")
-
-except Exception as e:
-    error_msg = f"Error processing PDF: {str(e)}"
-    print(error_msg)
-    shared_context['extracted_text'] = f"Error: {error_msg}"
-"""
-    },
-     {
-        "engine": "natural",
-        "code": """
-{% if shared_context and shared_context.extracted_text %}
-{% if shared_context.extracted_text.startswith('Error:') %}
-{{ shared_context.extracted_text }}
-{% else %}
-Here is the text extracted from the PDF:
-
-{{ shared_context.extracted_text }}
-
-Please provide a response to user request: {{ inputs.request }} using the information extracted above.
-{% endif %}
-{% else %}
-Error: No text was extracted from the PDF.
-{% endif %}
-"""
-    },]
-
-# Instantiate the tool
-tool = Tool(tool_data)
-
-# Create an NPC instance
-npc = NPC(
-    name='starlana',
-    primary_directive='Analyze text from Astrophysics papers with a keen attention to theoretical machinations and mechanisms.',
-    db_conn=sqlite3.connect(os.path.expanduser('~/npcsh_database.db'))
-)
-
-# Define input values dictionary
-input_values = {
-    "request": "what is the point of the yuan and narayanan work?",
-    "file": os.path.abspath("test_data/yuan2004.pdf")
-}
-
-print(f"Attempting to read file: {input_values['file']}")
-print(f"File exists: {os.path.exists(input_values['file'])}")
-
-# Execute the tool
-output = tool.execute(input_values, npc.tools_dict, None, 'Sample Command', npc)
-
-print('Tool Output:', output)
-```
-
 ## npcsql: SQL Integration and pipelines (UNDER CONSTRUCTION)