ngpt 3.8.3__tar.gz → 3.9.1__tar.gz

ngpt-3.9.1/.github/workflows/repo-mirror.yml

@@ -0,0 +1,75 @@
+name: Repository Mirroring
+
+on:
+  push:
+    branches: [ "main" ]
+  delete:
+    branches: [ "main" ]
+  workflow_dispatch:  # Allows manual triggering
+
+jobs:
+  mirror_to_gitlab:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+      - name: Configure Git
+        run: |
+          git config --global user.name "GitHub Actions"
+          git config --global user.email "actions@github.com"
+      - name: Mirror to GitLab
+        env:
+          SSH_PRIVATE_KEY: ${{ secrets.GITLAB_SSH_PRIVATE_KEY }}
+          TARGET_URL: ${{ secrets.GITLAB_REPO_URL }}
+        run: |
+          mkdir -p ~/.ssh
+          echo "${SSH_PRIVATE_KEY}" > ~/.ssh/id_rsa
+          chmod 600 ~/.ssh/id_rsa
+          ssh-keyscan gitlab.com >> ~/.ssh/known_hosts
+          # Push local branches and tags, excluding remote refs
+          git push --force ${TARGET_URL} 'refs/heads/*:refs/heads/*' 'refs/tags/*:refs/tags/*'
+  
+  mirror_to_gitea:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+      - name: Configure Git
+        run: |
+          git config --global user.name "GitHub Actions"
+          git config --global user.email "actions@github.com"
+      - name: Mirror to Gitea
+        env:
+          SSH_PRIVATE_KEY: ${{ secrets.GITEA_SSH_PRIVATE_KEY }}
+          TARGET_URL: ${{ secrets.GITEA_REPO_URL }}
+        run: |
+          mkdir -p ~/.ssh
+          echo "${SSH_PRIVATE_KEY}" > ~/.ssh/id_rsa
+          chmod 600 ~/.ssh/id_rsa
+          ssh-keyscan -t rsa $(echo ${TARGET_URL} | cut -d '@' -f 2 | cut -d ':' -f 1) >> ~/.ssh/known_hosts
+          # Push local branches and tags, excluding remote refs
+          git push --force ${TARGET_URL} 'refs/heads/*:refs/heads/*' 'refs/tags/*:refs/tags/*' 
+
+  mirror_to_codeberg:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+      - name: Configure Git
+        run: |
+          git config --global user.name "GitHub Actions"
+          git config --global user.email "actions@github.com"
+      - name: Mirror to Codeberg
+        env:
+          SSH_PRIVATE_KEY: ${{ secrets.CODEBERG_SSH_PRIVATE_KEY }}
+          TARGET_URL: ${{ secrets.CODEBERG_REPO_URL }}
+        run: |
+          mkdir -p ~/.ssh
+          echo "${SSH_PRIVATE_KEY}" > ~/.ssh/id_rsa
+          chmod 600 ~/.ssh/id_rsa
+          ssh-keyscan -t rsa codeberg.org >> ~/.ssh/known_hosts
+          # Push local branches and tags, excluding remote refs
+          git push --force ${TARGET_URL} 'refs/heads/*:refs/heads/*' 'refs/tags/*:refs/tags/*' 

{ngpt-3.8.3 → ngpt-3.9.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ngpt
-Version: 3.8.3
+Version: 3.9.1
 Summary: Swiss army knife for LLMs: powerful CLI and interactive chatbot in one package. Seamlessly work with OpenAI, Ollama, Groq, Claude, Gemini, or any OpenAI-compatible API to generate code, craft git commits, rewrite text, and execute shell commands.
 Project-URL: Homepage, https://github.com/nazdridoy/ngpt
 Project-URL: Repository, https://github.com/nazdridoy/ngpt
@@ -75,6 +75,7 @@ Description-Content-Type: text/markdown
 - 📝 **Rich Multiline Editor**: Interactive multiline text input with syntax highlighting and intuitive controls
 - 📑 **Git Commit Messages**: AI-powered generation of conventional, detailed commit messages from git diffs
 - 🎭 **System Prompts**: Customize model behavior with custom system prompts
+- 🤖 **Custom Roles**: Create and use reusable AI roles for specialized tasks
 - 📃 **Conversation Logging**: Save your conversations to text files for later reference
 - 🔌 **Modular Architecture**: Well-structured codebase with clean separation of concerns
 - 🔄 **Provider Switching**: Easily switch between different LLM providers with a single parameter
@@ -164,6 +165,17 @@ What is the best way to learn Golang?
 Provide simple hello world example.
 EOF
 
+# Create a custom role for specialized tasks
+ngpt --role-config create json_generator
+
+# Use a custom role for specific tasks
+ngpt --role json_generator "Generate user data with name, email, and address" 
+
+# Use a role from the Role Gallery (first create it, then use it)
+ngpt --role-config create sql_expert
+# Paste the SQL Expert role from https://nazdridoy.github.io/ngpt/examples/role-gallery/
+ngpt --role sql_expert "Write a query to find all users who made a purchase in the last 30 days"
+
 # Rewrite text to improve quality while preserving tone and meaning
 echo "your text" | ngpt -r
 
@@ -267,10 +279,11 @@ For more examples and detailed usage, visit the [CLI Usage Guide](https://nazdri
 
 usage: ngpt [-h] [-v] [--language LANGUAGE] [--config [CONFIG]] [--config-index CONFIG_INDEX] [--provider PROVIDER]
             [--remove] [--show-config] [--all] [--list-models] [--list-renderers] [--cli-config [COMMAND ...]]
-            [--api-key API_KEY] [--base-url BASE_URL] [--model MODEL] [--web-search] [--pipe]
-            [--temperature TEMPERATURE] [--top_p TOP_P] [--max_tokens MAX_TOKENS] [--log [FILE]] [--preprompt PREPROMPT]
-            [--no-stream | --prettify | --stream-prettify] [--renderer {auto,rich,glow}] [--rec-chunk] [--diff [FILE]]
-            [--chunk-size CHUNK_SIZE] [--analyses-chunk-size ANALYSES_CHUNK_SIZE] [--max-msg-lines MAX_MSG_LINES]
+            [--role-config [ACTION ...]] [--api-key API_KEY] [--base-url BASE_URL] [--model MODEL] [--web-search]
+            [--pipe] [--temperature TEMPERATURE] [--top_p TOP_P] [--max_tokens MAX_TOKENS] [--log [FILE]]
+            [--preprompt PREPROMPT | --role ROLE] [--no-stream | --prettify | --stream-prettify]
+            [--renderer {auto,rich,glow}] [--rec-chunk] [--diff [FILE]] [--chunk-size CHUNK_SIZE]
+            [--analyses-chunk-size ANALYSES_CHUNK_SIZE] [--max-msg-lines MAX_MSG_LINES]
             [--max-recursion-depth MAX_RECURSION_DEPTH] [-i | -s | -c | -t | -r | -g]
             [prompt]
 
@@ -297,6 +310,7 @@ Configuration Options::
 --list-models                       List all available models for the current configuration and exit
 --list-renderers                    Show available markdown renderers for use with --prettify
 --cli-config [COMMAND ...]          Manage CLI configuration (set, get, unset, list, help)
+--role-config [ACTION ...]          Manage custom roles (help, create, show, edit, list, remove) [role_name]
 
 Global Options::
 
@@ -310,6 +324,7 @@ Global Options::
 --max_tokens MAX_TOKENS             Set max response length in tokens
 --log [FILE]                        Set filepath to log conversation to, or create a temporary log file if no path provided
 --preprompt PREPROMPT               Set custom system prompt to control AI behavior
+--role ROLE                         Use a predefined role to set system prompt (mutually exclusive with --preprompt)
 --renderer {auto,rich,glow}         Select which markdown renderer to use with --prettify or --stream-prettify (auto, rich, or glow)
 
 Output Display Options (mutually exclusive)::
@@ -325,7 +340,7 @@ Git Commit Message Options::
 --chunk-size CHUNK_SIZE             Number of lines per chunk when chunking is enabled (default: 200)
 --analyses-chunk-size ANALYSES_CHUNK_SIZE Number of lines per chunk when recursively chunking analyses (default: 200)
 --max-msg-lines MAX_MSG_LINES       Maximum number of lines in commit message before condensing (default: 20)
---max-recursion-depth MAX_RECURSION_DEPTH  Maximum recursion depth for commit message condensing (default: 3)
+--max-recursion-depth MAX_RECURSION_DEPTH Maximum recursion depth for commit message condensing (default: 3)
 
 Modes (mutually exclusive)::
 
@@ -353,6 +368,8 @@ Key documentation sections:
 - [Installation Guide](https://nazdridoy.github.io/ngpt/installation/)
 - [CLI Usage Guide](https://nazdridoy.github.io/ngpt/usage/cli_usage/)
 - [Configuration Guide](https://nazdridoy.github.io/ngpt/configuration/)
+- [Custom Roles Guide](https://nazdridoy.github.io/ngpt/usage/roles/)
+- [Role Gallery](https://nazdridoy.github.io/ngpt/examples/role-gallery/)
 - [Examples & Tutorials](https://nazdridoy.github.io/ngpt/examples/basic/)
 - [Git Commit Message Guide](https://nazdridoy.github.io/ngpt/usage/gitcommsg/)
 
@@ -601,6 +618,40 @@ This is a huge time-saver. nGPT analyzes your git diff and generates a properly
 
 ![ngpt-g](https://raw.githubusercontent.com/nazdridoy/ngpt/main/previews/ngpt-g.png)
 
+#### Custom AI Roles
+
+```bash
+# Create a specialized role for JSON generation
+ngpt --role-config create json_generator
+
+# Use the custom role to generate structured data
+ngpt --role json_generator "Generate random user profile data"
+```
+```json
+{
+  "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
+  "firstName": "Aurora",
+  "lastName": "Reynolds",
+  "email": "aurora.reynolds@example.com",
+  "phone": "+1-555-0101",
+  "address": {
+    "street": "123 Main St",
+    "city": "Anytown",
+    "state": "CA",
+    "zipCode": "90210"
+  },
+  "birthDate": "1990-07-15",
+  "registrationDate": "2022-01-20",
+  "isActive": true,
+  "roles": [
+    "user",
+    "premium"
+  ]
+}
+```
+
+Custom roles allow you to create reusable AI personas for consistent responses across various prompts. For more details, see the [Custom Roles Guide](https://nazdridoy.github.io/ngpt/usage/roles/) and check out the [Role Gallery](https://nazdridoy.github.io/ngpt/examples/role-gallery/) for ready-to-use roles.
+
 #### Web Search Integration
 
 ```bash

{ngpt-3.8.3 → ngpt-3.9.1}/README.md

@@ -38,6 +38,7 @@
 - 📝 **Rich Multiline Editor**: Interactive multiline text input with syntax highlighting and intuitive controls
 - 📑 **Git Commit Messages**: AI-powered generation of conventional, detailed commit messages from git diffs
 - 🎭 **System Prompts**: Customize model behavior with custom system prompts
+- 🤖 **Custom Roles**: Create and use reusable AI roles for specialized tasks
 - 📃 **Conversation Logging**: Save your conversations to text files for later reference
 - 🔌 **Modular Architecture**: Well-structured codebase with clean separation of concerns
 - 🔄 **Provider Switching**: Easily switch between different LLM providers with a single parameter
@@ -127,6 +128,17 @@ What is the best way to learn Golang?
 Provide simple hello world example.
 EOF
 
+# Create a custom role for specialized tasks
+ngpt --role-config create json_generator
+
+# Use a custom role for specific tasks
+ngpt --role json_generator "Generate user data with name, email, and address" 
+
+# Use a role from the Role Gallery (first create it, then use it)
+ngpt --role-config create sql_expert
+# Paste the SQL Expert role from https://nazdridoy.github.io/ngpt/examples/role-gallery/
+ngpt --role sql_expert "Write a query to find all users who made a purchase in the last 30 days"
+
 # Rewrite text to improve quality while preserving tone and meaning
 echo "your text" | ngpt -r
 
@@ -230,10 +242,11 @@ For more examples and detailed usage, visit the [CLI Usage Guide](https://nazdri
 
 usage: ngpt [-h] [-v] [--language LANGUAGE] [--config [CONFIG]] [--config-index CONFIG_INDEX] [--provider PROVIDER]
             [--remove] [--show-config] [--all] [--list-models] [--list-renderers] [--cli-config [COMMAND ...]]
-            [--api-key API_KEY] [--base-url BASE_URL] [--model MODEL] [--web-search] [--pipe]
-            [--temperature TEMPERATURE] [--top_p TOP_P] [--max_tokens MAX_TOKENS] [--log [FILE]] [--preprompt PREPROMPT]
-            [--no-stream | --prettify | --stream-prettify] [--renderer {auto,rich,glow}] [--rec-chunk] [--diff [FILE]]
-            [--chunk-size CHUNK_SIZE] [--analyses-chunk-size ANALYSES_CHUNK_SIZE] [--max-msg-lines MAX_MSG_LINES]
+            [--role-config [ACTION ...]] [--api-key API_KEY] [--base-url BASE_URL] [--model MODEL] [--web-search]
+            [--pipe] [--temperature TEMPERATURE] [--top_p TOP_P] [--max_tokens MAX_TOKENS] [--log [FILE]]
+            [--preprompt PREPROMPT | --role ROLE] [--no-stream | --prettify | --stream-prettify]
+            [--renderer {auto,rich,glow}] [--rec-chunk] [--diff [FILE]] [--chunk-size CHUNK_SIZE]
+            [--analyses-chunk-size ANALYSES_CHUNK_SIZE] [--max-msg-lines MAX_MSG_LINES]
             [--max-recursion-depth MAX_RECURSION_DEPTH] [-i | -s | -c | -t | -r | -g]
             [prompt]
 
@@ -260,6 +273,7 @@ Configuration Options::
 --list-models                       List all available models for the current configuration and exit
 --list-renderers                    Show available markdown renderers for use with --prettify
 --cli-config [COMMAND ...]          Manage CLI configuration (set, get, unset, list, help)
+--role-config [ACTION ...]          Manage custom roles (help, create, show, edit, list, remove) [role_name]
 
 Global Options::
 
@@ -273,6 +287,7 @@ Global Options::
 --max_tokens MAX_TOKENS             Set max response length in tokens
 --log [FILE]                        Set filepath to log conversation to, or create a temporary log file if no path provided
 --preprompt PREPROMPT               Set custom system prompt to control AI behavior
+--role ROLE                         Use a predefined role to set system prompt (mutually exclusive with --preprompt)
 --renderer {auto,rich,glow}         Select which markdown renderer to use with --prettify or --stream-prettify (auto, rich, or glow)
 
 Output Display Options (mutually exclusive)::
@@ -288,7 +303,7 @@ Git Commit Message Options::
 --chunk-size CHUNK_SIZE             Number of lines per chunk when chunking is enabled (default: 200)
 --analyses-chunk-size ANALYSES_CHUNK_SIZE Number of lines per chunk when recursively chunking analyses (default: 200)
 --max-msg-lines MAX_MSG_LINES       Maximum number of lines in commit message before condensing (default: 20)
---max-recursion-depth MAX_RECURSION_DEPTH  Maximum recursion depth for commit message condensing (default: 3)
+--max-recursion-depth MAX_RECURSION_DEPTH Maximum recursion depth for commit message condensing (default: 3)
 
 Modes (mutually exclusive)::
 
@@ -316,6 +331,8 @@ Key documentation sections:
 - [Installation Guide](https://nazdridoy.github.io/ngpt/installation/)
 - [CLI Usage Guide](https://nazdridoy.github.io/ngpt/usage/cli_usage/)
 - [Configuration Guide](https://nazdridoy.github.io/ngpt/configuration/)
+- [Custom Roles Guide](https://nazdridoy.github.io/ngpt/usage/roles/)
+- [Role Gallery](https://nazdridoy.github.io/ngpt/examples/role-gallery/)
 - [Examples & Tutorials](https://nazdridoy.github.io/ngpt/examples/basic/)
 - [Git Commit Message Guide](https://nazdridoy.github.io/ngpt/usage/gitcommsg/)
 
@@ -564,6 +581,40 @@ This is a huge time-saver. nGPT analyzes your git diff and generates a properly
 
 ![ngpt-g](https://raw.githubusercontent.com/nazdridoy/ngpt/main/previews/ngpt-g.png)
 
+#### Custom AI Roles
+
+```bash
+# Create a specialized role for JSON generation
+ngpt --role-config create json_generator
+
+# Use the custom role to generate structured data
+ngpt --role json_generator "Generate random user profile data"
+```
+```json
+{
+  "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
+  "firstName": "Aurora",
+  "lastName": "Reynolds",
+  "email": "aurora.reynolds@example.com",
+  "phone": "+1-555-0101",
+  "address": {
+    "street": "123 Main St",
+    "city": "Anytown",
+    "state": "CA",
+    "zipCode": "90210"
+  },
+  "birthDate": "1990-07-15",
+  "registrationDate": "2022-01-20",
+  "isActive": true,
+  "roles": [
+    "user",
+    "premium"
+  ]
+}
+```
+
+Custom roles allow you to create reusable AI personas for consistent responses across various prompts. For more details, see the [Custom Roles Guide](https://nazdridoy.github.io/ngpt/usage/roles/) and check out the [Role Gallery](https://nazdridoy.github.io/ngpt/examples/role-gallery/) for ready-to-use roles.
+
 #### Web Search Integration
 
 ```bash

{ngpt-3.8.3 → ngpt-3.9.1}/docs/configuration.md

@@ -147,12 +147,15 @@ You can set configuration options directly via command-line arguments:
 ```
 usage: ngpt [-h] [-v] [--language LANGUAGE] [--config [CONFIG]] [--config-index CONFIG_INDEX] [--provider PROVIDER]
             [--remove] [--show-config] [--all] [--list-models] [--list-renderers] [--cli-config [COMMAND ...]]
-            [--api-key API_KEY] [--base-url BASE_URL] [--model MODEL] [--web-search] [--pipe]
-            [--temperature TEMPERATURE] [--top_p TOP_P] [--max_tokens MAX_TOKENS] [--log [FILE]] [--preprompt PREPROMPT]
-            [--no-stream | --prettify | --stream-prettify] [--renderer {auto,rich,glow}] [--rec-chunk] [--diff [FILE]]
-            [--chunk-size CHUNK_SIZE] [--analyses-chunk-size ANALYSES_CHUNK_SIZE] [--max-msg-lines MAX_MSG_LINES]
+            [--role-config [ACTION ...]] [--api-key API_KEY] [--base-url BASE_URL] [--model MODEL] [--web-search]
+            [--pipe] [--temperature TEMPERATURE] [--top_p TOP_P] [--max_tokens MAX_TOKENS] [--log [FILE]]
+            [--preprompt PREPROMPT | --role ROLE] [--no-stream | --prettify | --stream-prettify]
+            [--renderer {auto,rich,glow}] [--rec-chunk] [--diff [FILE]] [--chunk-size CHUNK_SIZE]
+            [--analyses-chunk-size ANALYSES_CHUNK_SIZE] [--max-msg-lines MAX_MSG_LINES]
             [--max-recursion-depth MAX_RECURSION_DEPTH] [-i | -s | -c | -t | -r | -g]
             [prompt]
+
+nGPT - Interact with AI language models via OpenAI-compatible APIs
 ```
 
 ### Positional Arguments
@@ -176,6 +179,7 @@ usage: ngpt [-h] [-v] [--language LANGUAGE] [--config [CONFIG]] [--config-index
 - `--list-models`: List all available models for the current configuration and exit
 - `--list-renderers`: Show available markdown renderers for use with --prettify
 - `--cli-config <[COMMAND ...]>`: Manage CLI configuration (set, get, unset, list, help)
+- `--role-config <[ACTION ...]>`: Manage custom roles (help, create, show, edit, list, remove) [role_name]
 
 ### Global Options
 
@@ -183,11 +187,13 @@ usage: ngpt [-h] [-v] [--language LANGUAGE] [--config [CONFIG]] [--config-index
 - `--base-url <BASE_URL>`: Base URL for the API
 - `--model <MODEL>`: Model to use
 - `--web-search`: Enable web search capability using DuckDuckGo to enhance prompts with relevant information
+- `--pipe`: Read from stdin and use content with prompt. Use {} in prompt as placeholder for stdin content. Can be used with any mode option except --text and --interactive
 - `--temperature <TEMPERATURE>`: Set temperature (controls randomness, default: 0.7)
 - `--top_p <TOP_P>`: Set top_p (controls diversity, default: 1.0)
 - `--max_tokens <MAX_TOKENS>`: Set max response length in tokens
 - `--log <[FILE]>`: Set filepath to log conversation to, or create a temporary log file if no path provided
 - `--preprompt <PREPROMPT>`: Set custom system prompt to control AI behavior
+- `--role <ROLE>`: Use a predefined role to set system prompt (mutually exclusive with --preprompt)
 - `--renderer <{auto,rich,glow}>`: Select which markdown renderer to use with --prettify or --stream-prettify (auto, rich, or glow)
 
 ### Output Display Options (mutually exclusive)
@@ -211,7 +217,6 @@ usage: ngpt [-h] [-v] [--language LANGUAGE] [--config [CONFIG]] [--config-index
 - `-s, --shell`: Generate and execute shell commands
 - `-c, --code`: Generate code
 - `-t, --text`: Enter multi-line text input (submit with Ctrl+D)
-- `--pipe`: Read from stdin and use content with prompt. Use {} in prompt as placeholder for stdin content. Can be used with any mode option except --text and --interactive.
 - `-r, --rewrite`: Rewrite text from stdin to be more natural while preserving tone and meaning
 - `-g, --gitcommsg`: Generate AI-powered git commit messages from staged changes or diff file
 
@@ -297,6 +302,64 @@ ngpt --list-models --provider OpenAI
 
 nGPT also supports a CLI configuration system for setting default parameter values. See the [CLI Configuration Guide](usage/cli_config.md) for details.
 
+## Role Configuration
+
+nGPT allows you to create and manage custom roles, which are saved system prompts that define specialized AI personas. Roles are stored in the following locations:
+
+- **Linux**: `~/.config/ngpt/ngpt_roles/`
+- **macOS**: `~/Library/Application Support/ngpt/ngpt_roles/`
+- **Windows**: `%APPDATA%\ngpt\ngpt_roles\`
+
+Each role is saved as a separate JSON file with the role name as the filename.
+
+### Managing Roles
+
+You can manage roles using the `--role-config` option:
+
+```bash
+# Show role configuration help
+ngpt --role-config help
+
+# Create a new role
+ngpt --role-config create expert_coder
+
+# List all available roles
+ngpt --role-config list
+
+# Show details of a specific role
+ngpt --role-config show expert_coder
+
+# Edit an existing role
+ngpt --role-config edit expert_coder
+
+# Remove a role
+ngpt --role-config remove expert_coder
+```
+
+When creating or editing a role, nGPT opens a multiline editor where you can enter or modify the system prompt for that role. This makes it easy to define complex instructions that guide the AI's behavior.
+
+### Using Roles
+
+To use a role, specify it with the `--role` parameter:
+
+```bash
+# Use a role in standard chat mode
+ngpt --role expert_coder "Create a function to parse JSON data"
+
+# Use a role with code generation
+ngpt --code --role python_expert "Create a class for managing user data"
+
+# Use a role with shell command generation
+ngpt --shell --role linux_expert "Find all large log files"
+
+# Use a role in interactive mode
+ngpt -i --role writing_assistant
+```
+
+The `--role` parameter is mutually exclusive with `--preprompt` since both set the system prompt.
+
+For detailed documentation on creating and managing roles, including examples and best practices, see the [Custom Roles Guide](usage/roles.md).
+
 ## Troubleshooting
 
 ### Common Configuration Issues
@@ -346,4 +409,4 @@ After configuring nGPT, explore:
 
 - [CLI Usage Guide](usage/cli_usage.md) for general usage information
 - [CLI Configuration Guide](usage/cli_config.md) for setting up default CLI options
-- [Basic Examples](examples/basic.md) for common usage patterns 
+- [Basic Examples](examples/basic.md) for common usage patterns