### Starting NPCsh Command Line Tool

Source: https://github.com/npc-worldwide/npcsh/blob/main/docs/installation.md

Command to launch the npcsh command-line interface after installation. This initiates the tool and its associated background processes.

```bash
npcsh
```

--------------------------------

### Install and Run Redis Server (Ubuntu)

Source: https://github.com/npc-worldwide/npcsh/blob/main/docs/npc_cli.md

Instructions for installing and starting the Redis server on Ubuntu, a prerequisite for serving the NPC project.

```bash
sudo apt update && sudo apt install redis-server
redis-server
```

--------------------------------

### Install and Run Redis Server (macOS)

Source: https://github.com/npc-worldwide/npcsh/blob/main/docs/npc_cli.md

Instructions for installing and starting the Redis server on macOS using Homebrew, a prerequisite for serving the NPC project.

```bash
brew install redis
redis-server
```

--------------------------------

### Project-Specific NPCSH Directory Structure

Source: https://github.com/npc-worldwide/npcsh/blob/main/docs/installation.md

This example shows how to set up project-specific NPCSH resources within a project's root directory. Including an `npc_team` directory allows NPCSH to recognize and utilize project-local NPCs, jinxs, assembly lines, models, and context files.

```bash
./npc_team/            # Project-specific NPCs
├── jinxs/             # Project jinxs #example jinx next
│   └── example.jinx
└── assembly_lines/    # Project workflows
    └── example.pipe
└── models/    # Project workflows
    └── example.model
└── example1.npc        # Example NPC
└── example2.npc        # Example NPC
└── team.ctx            # Example ctx
```

--------------------------------

### Example .env File for API Keys

Source: https://github.com/npc-worldwide/npcsh/blob/main/docs/installation.md

This bash snippet demonstrates the structure of a `.env` file used to store API keys for various LLM providers. These keys are used by NPCSH for authentication when interacting with services like OpenAI, Anthropic, and Gemini.

```bash
export OPENAI_API_KEY="your_openai_key"
export ANTHROPIC_API_KEY="your_anthropic_key"
export DEEPSEEK_API_KEY='your_deepseek_key'
export GEMINI_API_KEY='your_gemini_key'
export PERPLEXITY_API_KEY='your_perplexity_key'
```

--------------------------------

### Windows NPCsh Installation

Source: https://github.com/npc-worldwide/npcsh/blob/main/docs/installation.md

Installs ollama and ffmpeg on Windows, followed by npcsh installation using pip. Covers installing various npcsh packages with optional features for API libraries, local setup, TTS/STT, and a complete package.

```powershell
ollama pull llama3.2
ollama pull llava:7b
ollama pull nomic-embed-text
pip install npcpy
# if you want to install with the API libraries
pip install npcpy[lite]
# if you want the full local package set up (ollama, diffusers, transformers, cuda etc.)
pip install npcpy[local]
# if you want to use tts/stt
pip install npcpy[yap]

# if you want everything:
pip install npcpy[all]
```

--------------------------------

### Install and Start Ollama on macOS

Source: https://github.com/npc-worldwide/npcsh/blob/main/README.md

Installs Ollama on macOS using Homebrew, starts the Ollama service, and pulls essential AI models. This enables local execution of models like Llama 3.2, Llava 7b, and nomic-embed-text.

```bash
brew install ollama
brew services start ollama
ollama pull llama3.2
ollama pull llava:7b
ollama pull nomic-embed-text
```

--------------------------------

### Mac Dependencies and NPCsh Installation

Source: https://github.com/npc-worldwide/npcsh/blob/main/docs/installation.md

Installs necessary audio and trigger dependencies on macOS using Homebrew, followed by ollama and npcsh installation via pip. Includes commands for installing portaudio, ffmpeg, pygobject3, inotify-tools, and various npcsh packages.

```bash
#mainly for audio
brew install portaudio
brew install ffmpeg
brew install pygobject3

# for triggers
brew install inotify-tools


brew install ollama
brew services start ollama
ollama pull llama3.2
ollama pull llava:7b
ollama pull nomic-embed-text
pip install npcpy
# if you want to install with the API libraries
pip install npcpy[lite]
# if you want the full local package set up (ollama, diffusers, transformers, cuda etc.)
pip install npcpy[local]
# if you want to use tts/stt
pip install npcpy[yap]

# if you want everything:
pip install npcpy[all]
```

--------------------------------

### NPC Serving API

Source: https://github.com/npc-worldwide/npcsh/blob/main/docs/npc_cli.md

This section details how to serve an NPC project locally. It includes instructions for setting up prerequisites like Redis, starting the NPC server, and using flags for custom port configurations. Examples demonstrate serving with specific templates and contexts.

```APIDOC
## Serving NPC Projects

To serve an NPC project, first install and start `redis-server`.

**Ubuntu:**
```bash
sudo apt update && sudo apt install redis-server
redis-server
```

**macOS:**
```bash
brew install redis
redis-server
```

Then, navigate to your project directory and run:

```bash
pc serve
```

To specify a port, use the `-p` or `--port` flag:

```bash
pc serve -p 5337
# or
pc serve --port 5337
```

To initialize a project with templates and context:

```bash
pc serve -t 'sales, marketing' -ctx 'im developing a team that will focus on sales and marketing within the logging industry. I need a team that can help me with the following: - generate leads - create marketing campaigns - build a sales funnel - close deals - manage customer relationships - manage sales pipeline - manage marketing campaigns - manage marketing budget' -m llama3.2 -pr ollama
```

API endpoints will be available at `http://localhost:5337/api/`.
```

--------------------------------

### Linux Dependencies and NPCsh Installation

Source: https://github.com/npc-worldwide/npcsh/blob/main/docs/installation.md

Installs essential audio, trigger, and AI model dependencies on Linux systems using apt-get and pip. Includes installation of espeak, portaudio, ffmpeg, ollama, and various npcsh packages with optional features.

```bash
# for audio primarily
sudo apt-get install espeak
sudo apt-get install portaudio19-dev python3-pyaudio
sudo apt-get install alsa-base alsa-utils
sudo apt-get install libcairo2-dev
sudo apt-get install libgirepository1.0-dev
sudo apt-get install ffmpeg

# for triggers
sudo apt install inotify-tools


#And if you don't have ollama installed, use this:
curl -fsSL https://ollama.com/install.sh | sh

ollama pull llama3.2
ollama pull llava:7b
ollama pull nomic-embed-text
pip install npcpy
# if you want to install with the API libraries
pip install npcpy[lite]
# if you want the full local package set up (ollama, diffusers, transformers, cuda etc.)
pip install npcpy[local]
# if you want to use tts/stt
pip install npcpy[yap]

# if you want everything:
pip install npcpy[all]
```

--------------------------------

### Shell Initialization for NPCsh

Source: https://github.com/npc-worldwide/npcsh/blob/main/docs/installation.md

Adds npcsh initialization commands to shell configuration files like .bashrc or .zshrc. Ensures necessary variables are set when a new shell session starts.

```bash
# Example for .bashrc or .zshrc
# Add npcsh initialization commands here if not done automatically.
```

--------------------------------

### Install and Enter NPC Shell

Source: https://context7.com/npc-worldwide/npcsh/llms.txt

Instructions for installing NPC Shell with API provider support or local model support, followed by the command to enter the interactive shell. Examples show basic interaction, web search, NPC switching, and image generation within the shell.

```bash
# Install npcsh with API provider support
pip install 'npcsh[lite]'

# Or install with local model support
pip install 'npcsh[local]'

# Enter the NPC shell
pcsh

# Example session:
pcsh> can you help me identify what process is listening on port 5337?
# AI responds with analysis and bash commands

pcsh> /search "cerulean city" perplexity
# Searches the web using Perplexity

pcsh> /n sibiji
# Switch to a different NPC named sibiji

pcsh> /vixynt 'generate an image of a rabbit eating ham in the brink of dawn' model='gpt-image-1' provider='openai'
# Generates an image using OpenAI

# Exit the shell
pcsh> exit
```

--------------------------------

### Initialize NPC Project

Source: https://github.com/npc-worldwide/npcsh/blob/main/docs/npcsh.md

Sets up the basic infrastructure for an NPC team project. This command automates the creation of necessary files and configurations to start a new project. It simplifies the initial setup process.

```bash
# npcsh 
/init

# bash 
pc init
```

--------------------------------

### Python: Setting up Jinja Environment and NPC

Source: https://github.com/npc-worldwide/npcsh/blob/main/docs/TLDR_Cheat_sheet.md

Initializes a Jinja environment and an NPC (Non-Player Character) agent. The NPC is configured with a name, directive, model, provider, and a database connection. This setup is preparatory for executing Jinx workflows.

```python
from jinja2 import Environment, FileSystemLoader
import sqlite3
import os
from npcpy.npc_compiler import NPC, Jinx

jinja_env = Environment(loader=FileSystemLoader('.'))

jinx_data = {
    "jinx_name": "pdf_analyzer",
    "inputs": ["request", "file"],
    "steps": [
        {
            "engine": "python",
            "code": ""
        },
         {
            "engine": "natural",
            "code": ""
        },
    ]
    }


jinx = Jinx(jinx_data)

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'))
)

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'])}")

# Assuming npcjinxs_dict and messages are defined elsewhere
# output = jinx.execute(input_values, npcjinxs_dict, jinja_env, npc=npc, messages= messages)

# print('Jinx Output:', output)
```

--------------------------------

### Wander Mode CLI Usage with Ollama (Qwen3)

Source: https://github.com/npc-worldwide/npcsh/blob/main/docs/wander.md

This command-line example showcases Wander Mode execution with the Ollama provider and the Qwen3 model. It features a similar structure to the Deepseek example, demonstrating adaptability with different Ollama models.

```bash
npc wander "what is the goos hacnehn effect and how does it affect the water refraction" \
  --provider "ollama" \
  --model "qwen3:latest" \
  environment="a vast, dark ocean ." \
  interruption-likelihood=.1
```

--------------------------------

### Python: Create and Execute a Jinx

Source: https://github.com/npc-worldwide/npcsh/blob/main/docs/TLDR_Cheat_sheet.md

Shows how to define and execute a 'jinx' programmatically within a Python script. This example outlines the setup for a jinx that processes PDF files, extracts text, and answers user queries about the content, involving NLP and templating libraries.

```python
from npcpy.npc_compiler import Jinx, NPC
import sqlite3
import os

from jinja2 import Environment, FileSystemLoader
```

--------------------------------

### Install NPCsh Python Package

Source: https://github.com/npc-worldwide/npcsh/blob/main/README.md

Installs the npcsh Python package. Different options are provided for installing with varying levels of functionality, including API libraries ('lite'), full local setup ('local'), text-to-speech/speech-to-text ('yap'), and all features ('all').

```bash
pip install npcsh
# if you want to install with the API libraries
pip install 'npcsh[lite]'
# if you want the full local package set up (ollama, diffusers, transformers, cuda etc.)
pip install 'npcsh[local]'
# if you want to use tts/stt
pip install 'npcsh[yap]'
# if you want everything:
pip install 'npcsh[all]'
```

--------------------------------

### NQL Example Model for Command History Analysis (SQL)

Source: https://github.com/npc-worldwide/npcsh/blob/main/README.md

An example of an NQL model that analyzes command history to count command executions and synthesize insights using an AI function. This SQL file can be placed in the 'npc_team/models/' directory and executed on a schedule.

```sql
{{ config(materialized='table') }}

SELECT
    command,
    count(*) as exec_count,
    nql.synthesize(
        'Analyze "{command}" usage pattern with {exec_count} executions',
        'sibiji',
        'pattern_insight'
    ) as insight
FROM command_history
GROUP BY command

```

--------------------------------

### Fedora Specific Dependencies

Source: https://github.com/npc-worldwide/npcsh/blob/main/docs/installation.md

Lists additional package dependencies required for npcsh on Fedora systems. Includes python3-dev for Chroma DB compatibility and packages for pyautogui.

```text
- python3-dev (fixes hnswlib issues with chroma db)
- xhost +  (pyautogui)
- python-tkinter (pyautogui)
```

--------------------------------

### Wander Mode CLI Usage with OpenAI

Source: https://github.com/npc-worldwide/npcsh/blob/main/docs/wander.md

This example shows how to invoke Wander Mode using the OpenAI provider and model. It's similar to the Gemini example, showcasing the flexibility of Wander Mode across different LLM services.

```bash
npc --model "gpt-4o-mini" --provider "openai" wander "how does the goos-hanchen effect impact neutron scattering?" \
  environment='a ships library in the south.' \
  num-events=3 \
  n-high-temp-streams=10 \
  high-temp=1.95 \
  low-temp=0.4 \
  sample-rate=0.5 \
  interruption-likelihood=.1
```

--------------------------------

### Example NPCSH Configuration File (.npcshrc)

Source: https://github.com/npc-worldwide/npcsh/blob/main/README.md

An example of the `.npcshrc` file generated by NPCsh. This file contains environment variables that configure the NPC shell's behavior, such as database paths, default AI models for chat, embedding, image generation, reasoning, search, and vision.

```bash
# NPCSH Configuration File
export NPCSH_INITIALIZED=1
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
```

--------------------------------

### Load NPCSH Configuration Script

Source: https://github.com/npc-worldwide/npcsh/blob/main/docs/installation.md

This bash script checks for and sources the `~/.npcshrc` configuration file if it exists. This allows users to define custom environment variables or settings for NPCSH.

```bash
if [ -f ~/.npcshrc ]; then
    . ~/.npcshrc
fi
```

--------------------------------

### Install and Configure Ollama for AI Models

Source: https://github.com/npc-worldwide/npcsh/blob/main/README.md

Installs Ollama, a tool for running large language models locally, and pulls specific AI models. This command-line installation is cross-platform. It includes pulling the Llama 3.2, Llava 7b, and nomic-embed-text models.

```bash
curl -fsSL https://ollama.com/install.sh | sh

ollama pull llama3.2
ollama pull llava:7b
ollama pull nomic-embed-text
```

--------------------------------

### Install Dependencies for NPCsh on Linux

Source: https://github.com/npc-worldwide/npcsh/blob/main/README.md

Installs essential audio, trigger, and general dependencies for npcsh on Debian-based Linux systems. Includes packages for text-to-speech (espeak), audio handling (portaudio, pyaudio, alsa), graphics (cairo), Python introspection (girepository), and video processing (ffmpeg). Also installs inotify-tools for file system event monitoring.

```bash
sudo apt-get install espeak
sudo apt-get install portaudio19-dev python3-pyaudio
sudo apt-get install alsa-base alsa-utils
sudo apt-get install libcairo2-dev
sudo apt-get install libgirepository1.0-dev
sudo apt-get install ffmpeg

# for triggers
sudo apt install inotify-tools
```

--------------------------------

### Control Event Generation in NPC Interaction (Ollama)

Source: https://github.com/npc-worldwide/npcsh/blob/main/docs/npcsh.md

Shows how to start an NPC interaction with specific parameters for event generation and environment, using the 'ollama' provider. This example uses a smaller interruption likelihood for smoother interaction. Requires the 'npc' command-line tool and an Ollama model.

```bash
npc wander "what is the goos hanchen effect and does it affect water refraction?" \
--provider "ollama" \
--model "deepseek-r1:32b" \
environment="a vast, dark ocean ." \
interruption-likelihood=.1
```

--------------------------------

### Global NPCSH Directory Structure

Source: https://github.com/npc-worldwide/npcsh/blob/main/docs/installation.md

This illustrates the default directory structure for global NPCSH resources. It includes directories for images, scheduled jobs, logs, global NPCs, screenshots, and triggers, providing a standardized layout for core functionalities.

```bash
~/.npcsh/

└── images/ # images created or uploaded during conversations
└── jobs/ # scheduled jobs 
└── logs/ # logs for triggers and jobs
├── npc_team/           # Global NPCs
│   ├── jinxs/          # Global jinxs
│   └── assembly_lines/ # Workflow pipelines
└── screenshots/ # taken with the screenshot jinx or /ots macro
└── triggers/ # jobs that trigger on certain conditions
```

--------------------------------

### Wander Mode CLI Usage with Gemini

Source: https://github.com/npc-worldwide/npcsh/blob/main/docs/wander.md

This example demonstrates how to use the Wander Mode from the command line with the Gemini LLM provider and model. It specifies a problem, an environment, and various parameters to control LLM output and event generation.

```bash
npc --model "gemini-2.0-flash" --provider "gemini" wander "how does the bar of a galaxy influence the the surrounding IGM?" \
  environment='a ships library in the south.' \
  num-events=3 \
  n-high-temp-streams=10 \
  high-temp=1.95 \
  low-temp=0.4 \
  sample-rate=0.5 \
  interruption-likelihood=.1
```

--------------------------------

### Display Help in NPC Shell and CLI

Source: https://github.com/npc-worldwide/npcsh/blob/main/docs/npc_cli.md

This snippet shows how to get help for available macros. From within the NPC shell, use '/help'. From a regular bash shell, use 'npc --help' or 'npc -h'.

```npcsh
npcsh> /help
```

```bash
npc --help
#alternatively
pc -h
```

--------------------------------

### Add NPCsh to Shell Configuration

Source: https://github.com/npc-worldwide/npcsh/blob/main/README.md

Instructions for manually adding NPCsh initialization commands to the user's shell configuration file (e.g., `.bashrc` or `.zshrc`) if the installer does not automatically perform this step. This ensures NPCsh is correctly set up when the shell starts.

```bash
# Add the following to your .bashrc or .zshrc:
# (The specific commands to add are not provided in the input, but this indicates where they would go)
```

--------------------------------

### Wander Mode CLI Usage with Ollama (Deepseek)

Source: https://github.com/npc-worldwide/npcsh/blob/main/docs/wander.md

This command-line example illustrates using Wander Mode with the Ollama provider and the Deepseek R1 model. It highlights specifying a problem, environment, and interruption likelihood.

```bash
npc wander "what is the goos hacnehn effect and how does it affect the water refraction" \
  --provider "ollama" \
  --model "deepseek-r1:32b" \
  environment="a vast, dark ocean ." \
  interruption-likelihood=.1
```

--------------------------------

### Example Guac Mode Interactive Output

Source: https://github.com/npc-worldwide/npcsh/blob/main/docs/guac.md

Illustrates the output of an interactive command in Guac Mode, showing both the LLM-generated Python code and its execution result.

```shell
(npcsh) caug@pop-os:/media/caug/extradrive1/npcww/npcsh$ guac
gLoaded .env file from /media/caug/extradrive1/npcww/npcsh
hows iloading npc team from directory
Error loading team context: 'Team' object has no attribute 'jinja_env'
filename:  guac.npc
filename:  toon.npc
filename:  parsely.npc
filename:  caug.npc
filename:  team.ctx
🥑 hows it going

# Generated python code:
print("I'm doing well, thank you! How can I assist you with Python today?")

I'm doing well, thank you! How can I assist you with Python today?
```

--------------------------------

### Python: Creating Sample Sales Data with Pandas

Source: https://github.com/npc-worldwide/npcsh/blob/main/docs/TLDR_Cheat_sheet.md

Generates a Pandas DataFrame with synthetic sales data including date, revenue, customer count, average ticket, region, and channel. The data is saved to a CSV file and returned as a DataFrame. Includes sinusoidal patterns for revenue and adjustments for specific channels.

```python
import pandas as pd
import numpy as np
import os

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),
        }
    )

  
    sales_data["revenue"] *= 1 + 0.3 * np.sin(
        np.pi * np.arange(90) / 30
    )
    sales_data.loc[sales_data["channel"] == "Mobile", "revenue"] *= 1.1
    sales_data.loc[
        sales_data["channel"] == "Online", "customer_count"
    ] *= 1.2

    sales_data.to_csv(filepath, index=False)
    return filepath, sales_data
```

--------------------------------

### Install Dependencies for NPCsh on macOS

Source: https://github.com/npc-worldwide/npcsh/blob/main/README.md

Installs necessary dependencies for npcsh on macOS using Homebrew. This includes audio handling (portaudio), video processing (ffmpeg), Python bindings for GObject (pygobject3), and file system event monitoring (inotify-tools).

```bash
#mainly for audio
brew install portaudio
brew install ffmpeg
brew install pygobject3

# for triggers
brew install inotify-tools
```

--------------------------------

### NQL Function Example: Sample Text Variations (SQL)

Source: https://github.com/npc-worldwide/npcsh/blob/main/README.md

Demonstrates calling a team jinx ('sample') as an NQL function to generate text variations based on a given text and NPC context. This showcases how team jinxs can be integrated into NQL models.

```sql
nql.sample('Generate variations of: {text}', 'frederic', 'variations')
```

--------------------------------

### Install NPC Shell with Local Model Support

Source: https://github.com/npc-worldwide/npcsh/blob/main/README.md

Installs the 'npcsh' package with support for running local LLM models. This option includes dependencies like diffusers, transformers, and torch, resulting in a larger installation size.

```bash
pip install 'npcsh[local]'
```

--------------------------------

### Install NPC Shell with API Model Support

Source: https://github.com/npc-worldwide/npcsh/blob/main/README.md

Installs the 'npcsh' package with support for using models through various APIs, as managed by litellm. This is suitable for users who primarily interact with cloud-based LLMs.

```bash
pip install 'npcsh[lite]'
```

--------------------------------

### Delegation Jinx Command Example

Source: https://github.com/npc-worldwide/npcsh/blob/main/README.md

Illustrates the command-line invocation of the '/delegate' jinx to assign a task to a specific NPC ('corca') with a defined maximum number of iterations. This demonstrates how tasks are delegated and managed within the npcsh orchestration system.

```bash
/delegate npc_name=corca task="Write a Python function to parse JSON files" max_iterations=5
```

--------------------------------

### Example Guac Mode Session Transcript

Source: https://github.com/npc-worldwide/npcsh/blob/main/docs/guac.md

Demonstrates a typical interactive session within Guac Mode, showcasing the use of shell commands, Python code execution, LLM-powered code generation from natural language, and the refresh cycle.

```shell
🥑 ls
# Lists files in the current directory
🥑 cd npcpy
# Changes directory
🥑 print("Hello, world!")
# Executes Python code
🥑 What is the mean of [1,2,3,4]?
# LLM generates and executes code to compute the mean
🥑 /refresh
# LLM suggests new helper functions based on your session
```

--------------------------------

### Python: Create and Use an NPC for Question Answering

Source: https://github.com/npc-worldwide/npcsh/blob/main/docs/TLDR_Cheat_sheet.md

Demonstrates how to instantiate an NPC object in Python, specifying its name, primary directive, and AI model. It then shows how to use the NPC to answer a question based on its directive and a connected SQLite database.

```python
import sqlite3
from npcpy.npc_compiler import NPC

# Set up database connection
db_path = '~/npcsh_history.db'
conn = sqlite3.connect(db_path)

# Load NPC from a file
pc = 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'])
```

--------------------------------

### Serve NPC Project with Templates and Context

Source: https://github.com/npc-worldwide/npcsh/blob/main/docs/npc_cli.md

Command to initialize an NPC project using templates and context, then serve it. Specifies the model and provider for NPC generation.

```bash
npc serve -t 'sales, marketing' -ctx 'im developing a team that will focus on sales and marketing within the logging industry. I need a team that can help me with the following: - generate leads - create marketing campaigns - build a sales funnel - close deals - manage customer relationships - manage sales pipeline - manage marketing campaigns - manage marketing budget' -m llama3.2 -pr ollama
```

--------------------------------

### Serve NPC Project

Source: https://github.com/npc-worldwide/npcsh/blob/main/docs/npc_cli.md

Command to serve the NPC project from its directory. Allows specifying a custom port using -p or --port flags.

```bash
npc serve
npc serve -p 5337
npc serve --port 5337
```

--------------------------------

### Running NQL Models via CLI

Source: https://github.com/npc-worldwide/npcsh/blob/main/README.md

The `nql` command-line interface provides various options for managing and running NQL models. You can list models, run them in dependency order, specify individual models, use different databases, define output schemas, and schedule them with cron.

```bash
# List available models (shows [NQL] tag for models with AI functions)
nql show=1

# Run all models in dependency order
nql

# Run a specific model
nql model=daily_summary

# Use a different database
nql db=~/analytics.db

# Specify output schema
nql schema=analytics

# Schedule with cron (runs daily at 6am)
nql install_cron="0 6 * * *"
```

--------------------------------

### Install NPCsh Python Package on macOS

Source: https://github.com/npc-worldwide/npcsh/blob/main/README.md

Installs the npcsh Python package on macOS. Provides options for installing with specific feature sets like API libraries ('lite'), full local setup ('local'), TTS/STT capabilities ('yap'), or all available features ('all').

```bash
pip install npcsh
# if you want to install with the API libraries
pip install npcsh[lite]
# if you want the full local package set up (ollama, diffusers, transformers, cuda etc.)
pip install npcsh[local]
# if you want to use tts/stt
pip install npcsh[yap]

# if you want everything:
pip install npcsh[all]
```

--------------------------------

### Install NPCsh Python Package on Windows (PowerShell)

Source: https://github.com/npc-worldwide/npcsh/blob/main/README.md

Installs the npcsh Python package on Windows via PowerShell. Offers different installation options for varying feature sets, including 'lite' for API libraries, 'local' for a full local setup, 'yap' for TTS/STT, and 'all' for complete functionality.

```powershell
ollama pull llama3.2
ollama pull llava:7b
ollama pull nomic-embed-text
pip install npcsh
# if you want to install with the API libraries
pip install 'npcsh[lite]'
# if you want the full local package set up (ollama, diffusers, transformers, cuda etc.)
pip install 'npcsh[local]'
# if you want to use tts/stt
pip install 'npcsh[yap]'

# if you want everything:
pip install 'npcsh[all]'
```

--------------------------------

### Get Help with Tasks using NPC

Source: https://github.com/npc-worldwide/npcsh/blob/main/README.md

This command allows users to ask for assistance with specific tasks. The system interprets the natural language query to identify the user's intent and provides relevant information or actions. For example, identifying a process listening on a specific port.

```bash
npcsh>can you help me identify what process is listening on port 5337?
```

--------------------------------

### Run NQL SQL Models with AI Transformations (Bash)

Source: https://context7.com/npc-worldwide/npcsh/llms.txt

Execute SQL models enhanced with AI transformations using the NQL command-line interface. NQL supports various databases and can schedule model runs. It translates NQL AI functions to native AI integrations for supported platforms or uses a Python fallback.

```bash
# List available models (shows [NQL] tag for models with AI functions)
nql show=1

# Run all models in dependency order
nql

# Run a specific model
nql model=daily_summary

# Use a different database
nql db=~/analytics.db

# Specify output schema
nql schema=analytics

# Schedule with cron (runs daily at 6am)
nql install_cron="0 6 * * *"

# From npcsh
pcsh> /nql show=1
pcsh> /nql model=command_patterns

# Example SQL model with AI functions (place in npc_team/models/)
# models/insights/command_patterns.sql
{{ config(materialized='table') }}

SELECT
    command,
    count(*) as exec_count,
    nql.synthesize(
        'Analyze "{command}" usage pattern with {exec_count} executions',
        'sibiji',
        'pattern_insight'
    ) as insight
FROM command_history
GROUP BY command
```

--------------------------------

### Python: PDF Text Extraction with PyMuPDF

Source: https://github.com/npc-worldwide/npcsh/blob/main/docs/TLDR_Cheat_sheet.md

Extracts text from a PDF file using the PyMuPDF library. It opens the PDF, iterates through pages to get text, closes the document, and stores the extracted text. Handles potential errors during processing.

```python
import fitz

shared_context = {}
shared_context['inputs'] = '{{request}}'

pdf_path = '{{file}}'


doc = fitz.open(pdf_path)
text = ""

for page_num in range(len(doc)):
    page = doc[page_num]
    text += page.get_text()

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")
```

--------------------------------

### Install NPC Shell with Voice Mode (yap)

Source: https://github.com/npc-worldwide/npcsh/blob/main/README.md

Installs the 'npcsh' package with support for the 'yap' voice mode. Users may need to follow OS-specific instructions to install necessary system audio libraries.

```bash
pip install 'npcsh[yap]'
```

--------------------------------

### Generate Video using AI

Source: https://github.com/npc-worldwide/npcsh/blob/main/README.md

Creates a video from a text prompt. This command specifies the prompt, the video generation model, and the AI engine to be used.

```bash
/roll 'generate a video of a hat riding a dog' veo-3.1-fast-generate-preview  gemini
```

--------------------------------

### Jinx Commands for Content Generation

Source: https://github.com/npc-worldwide/npcsh/blob/main/README.md

Generate and edit images and videos, or perform context-free LLM prompting using these jinx commands. They offer powerful creative and text-generation capabilities, allowing for dynamic content creation. Specify desired models and providers for tailored results.

```bash
# /vixynt: Generate/edit images.
/vixynt 'description' --igmodel gpt-image-1 --igprovider openai

# /roll: Generate videos.
/roll 'description' --vgmodel veo-3.1-fast-generate-preview --vgprovider gemini

# /sample: Context-free LLM prompt.
/sample 'question' -m gpt-4o-mini --temp 0.7
```

--------------------------------

### One-Shot LLM Sampling (`/sample`)

Source: https://github.com/npc-worldwide/npcsh/blob/main/docs/npcsh.md

The `/sample` command enables one-shot sampling from Large Language Models (LLMs) with customizable parameters. It supports various models and providers, including Ollama, Gemini, Claude, Qwen, and OpenAI. Parameters like temperature and top-k can be adjusted for different sampling behaviors.

```npcsh
/sample 'prompt'
/sample -m gemini-1.5-flash "Summarize the plot of 'The Matrix' in three sentences."
/sample --model claude-3-5-haiku-latest "Translate 'good morning' to Japanese."
/sample model=qwen3:latest "tell me about the last time you went shopping."
```

```bash
npc sample -p ollama -m gemma3:12b --temp 1.8 --top_k 50 "Write a haiku about the command line."
pc sample model=gpt-4o-mini "What are the primary colors?" --provider openai
```

--------------------------------

### Install Dependencies for NPCsh on Fedora

Source: https://github.com/npc-worldwide/npcsh/blob/main/README.md

Installs specific development packages required for npcsh on Fedora Linux. Includes python3-dev for potential build issues with libraries like chroma db, and packages for the pyautogui library.

```bash
python3-dev #(fixes hnswlib issues with chroma db)
xhost +  (pyautogui)
python-tkinter (pyautogui)
```

--------------------------------

### Start Reasoning REPL Loop with PTI

Source: https://github.com/npc-worldwide/npcsh/blob/main/docs/npcsh.md

Starts a reasoning Read-Eval-Print Loop (REPL) with interruptions. This command allows for interactive reasoning sessions, specifying the NPC name, model, and platform. It's useful for complex problem-solving and debugging.

```bash
npcsh
/pti  -n frederic -m qwen3:latest -p ollama 
```

--------------------------------

### /sample: One-shot Sampling from LLMs

Source: https://github.com/npc-worldwide/npcsh/blob/main/docs/npcsh.md

The /sample command allows for one-shot sampling from Large Language Models with specific parameters.

```APIDOC
## /sample: One-shot Sampling from LLMs

### Description
Perform one-shot sampling from LLMs with specific parameters.

### Method
POST (implied by command-line usage)

### Endpoint
/sample

### Parameters
#### Path Parameters
None.

#### Query Parameters
- `prompt` (string) - The prompt to send to the LLM.
- `-m` or `--model` (string) - The model to use (e.g., 'gemini-1.5-flash', 'claude-3-5-haiku-latest', 'qwen3:latest', 'gpt-4o-mini').
- `-p` or `--provider` (string) - The provider for the LLM (e.g., 'ollama', 'openai').
- `--temp` (float) - The temperature setting for the generation.
- `--top_k` (integer) - The top-k sampling parameter.

### Request Example
```npcsh
/sample 'prompt'
/sample -m gemini-1.5-flash "Summarize the plot of 'The Matrix' in three sentences."
/sample --model claude-3-5-haiku-latest "Translate 'good morning' to Japanese."
/sample model=qwen3:latest "tell me about the last time you went shopping."
```
```bash
npc sample -p ollama -m gemma3:12b --temp 1.8 --top_k 50 "Write a haiku about the command line."
pc sample model=gpt-4o-mini "What are the primary colors?" --provider openai
```

### Response
Text generated by the LLM.
```

--------------------------------

### NQL - AI-Powered SQL Models

Source: https://github.com/npc-worldwide/npcsh/blob/main/README.md

Enables running SQL models with embedded AI transformations using NPC agents. It supports listing available models, running all models, running specific models, and scheduling model execution with cron.

```bash
# List available models
nql show=1
```

```bash
# Run all models in dependency order
nql
```

```bash
# Run a specific model
nql model=daily_summary
```

```bash
# Schedule with cron (runs daily at 6am)
nql install_cron="0 6 * * *"
```

--------------------------------

### Python: NPC for Data Analysis

Source: https://github.com/npc-worldwide/npcsh/blob/main/docs/TLDR_Cheat_sheet.md

Illustrates using an NPC to analyze data from a Pandas DataFrame. This example sets up a database connection, creates a sample DataFrame, saves it to SQL, and then uses an NPC to generate a report based on the data and its primary directive.

```python
from npcpy.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)


pc = 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?')
```

--------------------------------

### NQL - AI-Powered SQL Models

Source: https://github.com/npc-worldwide/npcsh/blob/main/README.md

Runs SQL models with embedded AI transformations using NPC agents, supporting listing, running, and scheduling models.

```APIDOC
## NQL - AI-Powered SQL Models

### Description
NQL allows running SQL models enhanced with AI transformations powered by NPC agents. It supports listing available models, running them individually or in dependency order, and scheduling them with cron.

### Method
CLI Command

### Endpoint
nql

### Parameters
#### Options
- **show=1** - Lists available NQL models.
- (No arguments) - Runs all models in dependency order.
- **model** (string) - Specifies a particular model to run (e.g., `model=daily_summary`).
- **install_cron** (string) - Schedules the NQL execution with a cron expression (e.g., `install_cron="0 6 * * *"`).

### Request Example
```bash
nql show=1
nql
nql model=daily_summary
nql install_cron="0 6 * * *"
```

### Response Example
(Executes the NQL models and returns results, or confirms scheduling.)
```

--------------------------------

### Yap Voice Chat Mode: Installation and Python Usage

Source: https://context7.com/npc-worldwide/npcsh/llms.txt

Enables voice-activated conversation using speech-to-text and text-to-speech. Installation involves pip and system dependencies. Python usage requires initializing an NPC object and calling enter_yap_mode with specified models and files. The stream parameter is set to False for non-streaming interaction.

```bash
# Install voice dependencies
pip install 'npcsh[yap]'

# System dependencies (Ubuntu/Debian)
sudo apt-get install espeak portaudio19-dev python3-pyaudio ffmpeg

# Enter yap mode
pc yap -n assistant

# From npcsh with custom models
pcsh> /yap -n chatbot --model gpt-4o-mini --provider openai
```

```python
from npcsh.yap import enter_yap_mode
from npcpy.npc_compiler import NPC

pc = NPC(file="~/.npcsh/npc_team/sibiji.npc")
result = enter_yap_mode(
    npc=npc,
    model="gemini-1.5-flash",
    provider="gemini",
    tts_model="kokoro",
    voice="af_heart",
    files=["./context.txt"],
    rag_similarity_threshold=0.3,
    stream=False
)
# Voice interaction loop with VAD (Voice Activity Detection)
# Automatically detects speech and responds with audio output
```

--------------------------------

### General Help and Task Assistance

Source: https://github.com/npc-worldwide/npcsh/blob/main/README.md

Provides help with tasks and identifies processes listening on specific ports.

```APIDOC
## General Help and Task Assistance

### Description
Use the `npcsh` command to get assistance with various tasks, such as identifying processes listening on a specific port.

### Method
Interactive CLI

### Endpoint
npscsh

### Request Example
```bash
npcsh> can you help me identify what process is listening on port 5337?
```

### Response Example
(Displays information about the process listening on the specified port, potentially with a supporting image.)
```

--------------------------------

### Flush Conversation Context

Source: https://github.com/npc-worldwide/npcsh/blob/main/docs/npcsh.md

Clears the current conversation context, allowing for a fresh start. This is useful when a conversation is no longer productive.

```bash
/flush
```

--------------------------------

### Video Generation (Roll)

Source: https://context7.com/npc-worldwide/npcsh/llms.txt

Generate videos from text descriptions using various AI models and providers.

```APIDOC
## Video Generation (Roll)

### Description
Generate videos from text descriptions.

### Method
CLI Command

### Endpoint
N/A

### Parameters

#### Command Line Arguments
- **prompt** (string) - Required - The text description for video generation.
- **--vgmodel** (string) - Optional - Specify the video generation model to use.
- **--vgprovider** (string) - Optional - Specify the provider for the video generation model.
- **--provider** (string) - Optional - Specify a custom provider for video generation.
- **--model** (string) - Optional - Specify a custom model for video generation.

### Request Example
```bash
# Generate video with Gemini
pc roll 'generate a video of a hat riding a dog' veo-3.1-fast-generate-preview gemini

# Generate video with a specific model and provider
pc roll 'a cat dancing in the rain' --vgmodel stable-diffusion-v1-5 --vgprovider diffusers

# Generate video with a custom provider and model
npc roll --provider ollama --model llama3 "a cat dancing in the rain"
```

### Response
N/A (CLI output varies, video generation may save to a file or stream)

### Error Handling
N/A
```

--------------------------------

### Run NPC Shell

Source: https://github.com/npc-worldwide/npcsh/blob/main/README.md

Command to launch the NPC Shell interface after installation. This provides access to the enhanced command-line environment for agent interaction.

```bash
npcsh
```

--------------------------------

### NPC API Endpoints

Source: https://github.com/npc-worldwide/npcsh/blob/main/docs/npc_cli.md

Provides examples of how to interact with the NPC API endpoints using curl. This includes checking the server health, executing commands, retrieving conversations, and fetching messages within a conversation.

```APIDOC
## NPC API Endpoints Examples

Access the API at `http://localhost:5337/api/`.

### Health Check

Tests the server's health status.

```bash
curl -s http://localhost:5337/api/health | jq '.'
```

### Execute Command

Executes a given command string within the specified context.

**Method:** POST
**Endpoint:** `/api/execute`

**Request Body:**
```json
{
  "commandstr": "string",
  "currentPath": "string",
  "conversationId": "string"
}
```

**Example:**
```bash
curl -s -X POST http://localhost:5337/api/execute \
  -H "Content-Type: application/json" \
  -d '{"commandstr": "hello world", "currentPath": "~/", "conversationId": "test124"}' | jq '.'
```

### Conversations

Retrieves a list of conversations for a given path.

**Method:** GET
**Endpoint:** `/api/conversations?path={path}`

**Query Parameters:**
- **path** (string) - Required - The path to search for conversations.

**Example:**
```bash
curl -s "http://localhost:5337/api/conversations?path=/tmp" | jq '.'
```

### Conversation Messages

Fetches messages for a specific conversation.

**Method:** GET
**Endpoint:** `/api/conversation/{conversationId}/messages`

**Path Parameters:**
- **conversationId** (string) - Required - The ID of the conversation.

**Example:**
```bash
curl -s http://localhost:5337/api/conversation/test123/messages | jq '.'
```
```

--------------------------------

### Start Guac Mode in NPC Shell

Source: https://github.com/npc-worldwide/npcsh/blob/main/docs/guac.md

Initiates the Guac Mode interactive environment within the NPC Shell. This is the primary entry point for using Guac Mode's features.

```zsh
npcsh
# then type: guac
```

--------------------------------

### Begin Conversation with a Specified NPC

Source: https://github.com/npc-worldwide/npcsh/blob/main/docs/npcsh.md

Shows the syntax for starting a conversation with a specific NPC within the npcsh environment. This is done by referencing the NPC's name using a forward slash prefix.

```npcsh
npcsh> /<npc_name>:
```

--------------------------------

### Launch yap with Specific NPC

Source: https://github.com/npc-worldwide/npcsh/blob/main/docs/yap.md

Starts a 'yap' voice interaction session with a specified NPC. Replace '<npc_name>' with the target NPC's name. Requires a working microphone and audio dependencies.

```bash
yap -n <npc_name>
```