ngpt 2.7.2__tar.gz → 2.9.0__tar.gz

{ngpt-2.7.2 → ngpt-2.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ngpt
-Version: 2.7.2
+Version: 2.9.0
 Summary: A lightweight Python CLI and library for interacting with OpenAI-compatible APIs, supporting both official and self-hosted LLM endpoints.
 Project-URL: Homepage, https://github.com/nazdridoy/ngpt
 Project-URL: Repository, https://github.com/nazdridoy/ngpt
@@ -28,10 +28,9 @@ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: Utilities
 Requires-Python: >=3.8
+Requires-Dist: prompt-toolkit>=3.0.0
 Requires-Dist: requests>=2.31.0
-Provides-Extra: full
-Requires-Dist: prompt-toolkit>=3.0.0; extra == 'full'
-Requires-Dist: rich>=10.0.0; extra == 'full'
+Requires-Dist: rich>=10.0.0
 Description-Content-Type: text/markdown
 
 # nGPT
@@ -43,6 +42,9 @@ Description-Content-Type: text/markdown
 
 A lightweight Python CLI and library for interacting with OpenAI-compatible APIs, supporting both official and self-hosted LLM endpoints.
 
+![2025-04-23_16-18-01](https://github.com/user-attachments/assets/b8e58926-5165-4352-b48b-9f4a982da86e)
+
+
 ## Table of Contents
 - [Quick Start](#quick-start)
 - [Features](#features)
@@ -52,8 +54,10 @@ A lightweight Python CLI and library for interacting with OpenAI-compatible APIs
   - [Documentation](https://nazdridoy.github.io/ngpt/)
   - [CLI Tool](#as-a-cli-tool)
   - [Python Library](#as-a-library)
+  - [CLI Framework](#as-a-cli-framework)
 - [Configuration](#configuration)
   - [Command Line Options](#command-line-options)
+  - [CLI Configuration](#cli-configuration)
   - [Interactive Configuration](#interactive-configuration)
   - [Configuration File](#configuration-file)
   - [Configuration Priority](#configuration-priority)
@@ -63,11 +67,14 @@ A lightweight Python CLI and library for interacting with OpenAI-compatible APIs
 ## Quick Start
 
 ```bash
-# Install
+# Install with pip
 pip install ngpt
 
-# Install with additional features
-pip install "ngpt[full]"
+# Or install with uv (faster)
+uv pip install ngpt
+
+# Or install globally as a CLI tool (recommended)
+uv tool install ngpt
 
 # Chat with default settings
 ngpt "Tell me about quantum computing"
@@ -113,8 +120,8 @@ For more examples and detailed usage, visit the [CLI Usage Guide](https://nazdri
 
 ## Features
 
-- ✅ **Dual Mode**: Use as a CLI tool or import as a Python library
-- 🪶 **Lightweight**: Minimal dependencies (just `requests`)
+- ✅ **Versatile**: Use as a CLI tool, Python library, or CLI framework for building custom tools
+- 🪶 **Lightweight**: Minimal dependencies with everything you need included
 - 🔄 **API Flexibility**: Works with OpenAI, Ollama, Groq, and any compatible endpoint
 - 💬 **Interactive Chat**: Continuous conversation with memory in modern UI
 - 📊 **Streaming Responses**: Real-time output for better user experience
@@ -127,6 +134,7 @@ For more examples and detailed usage, visit the [CLI Usage Guide](https://nazdri
 - 📝 **Rich Multiline Editor**: Interactive multiline text input with syntax highlighting and intuitive controls
 - 🎭 **System Prompts**: Customize model behavior with custom system prompts
 - 📃 **Conversation Logging**: Save your conversations to text files for later reference
+- 🧰 **CLI Components**: Reusable components for building custom AI-powered command-line tools
 
 See the [Feature Overview](https://nazdridoy.github.io/ngpt/overview.html) for more details.
 
@@ -140,25 +148,25 @@ Key documentation sections:
 - [Installation Guide](https://nazdridoy.github.io/ngpt/installation.html)
 - [CLI Usage Guide](https://nazdridoy.github.io/ngpt/usage/cli_usage.html)
 - [Library Usage Guide](https://nazdridoy.github.io/ngpt/usage/library_usage.html)
+- [CLI Framework Guide](https://nazdridoy.github.io/ngpt/usage/cli_framework.html)
 - [Configuration Guide](https://nazdridoy.github.io/ngpt/configuration.html)
 - [Examples & Tutorials](https://nazdridoy.github.io/ngpt/examples/basic.html)
 
 ## Installation
 
 ```bash
-# Basic installation (minimal dependencies)
+# Installation with pip
 pip install ngpt
 
-# Full installation with all features (recommended)
-pip install "ngpt[full]"
+# Or install with uv (faster installation)
+uv pip install ngpt
+
+# Or install globally as a CLI tool (recommended for command-line usage)
+uv tool install ngpt
 ```
 
 Requires Python 3.8 or newer.
 
-The full installation includes:
-- Enhanced markdown rendering with syntax highlighting
-- Improved interactive input experience with multiline editing
-
 For detailed installation instructions, see the [Installation Guide](https://nazdridoy.github.io/ngpt/installation.html).
 
 ## Usage
@@ -278,6 +286,47 @@ print(code)
 
 For advanced usage patterns and integrations, check out the [Advanced Examples](https://nazdridoy.github.io/ngpt/examples/advanced.html).
 
+### As a CLI Framework
+
+nGPT can also be used as a framework to build your own AI-powered command-line tools. You can leverage nGPT's pre-built CLI components to quickly develop sophisticated CLI applications.
+
+```python
+from ngpt import NGPTClient, load_config
+from ngpt.cli import interactive_chat_session, prettify_markdown, ColoredHelpFormatter
+import argparse
+
+# Create a custom CLI tool with colorized help
+parser = argparse.ArgumentParser(
+    description="Specialized Code Assistant",
+    formatter_class=ColoredHelpFormatter
+)
+parser.add_argument("prompt", nargs="?", help="Code description")
+parser.add_argument("--language", "-l", default="python", help="Programming language")
+parser.add_argument("--interactive", "-i", action="store_true", help="Start interactive mode")
+args = parser.parse_args()
+
+# Initialize client
+client = NGPTClient(**load_config())
+
+# Use interactive session for conversation
+if args.interactive:
+    system_prompt = f"You are an expert {args.language} developer. Provide clear, detailed answers."
+    interactive_chat_session(client=client, preprompt=system_prompt, prettify=True)
+elif args.prompt:
+    # Generate and prettify code
+    code = client.generate_code(args.prompt, language=args.language)
+    print(prettify_markdown(f"```{args.language}\n{code}\n```"))
+```
+
+This allows you to build specialized AI tools like:
+- Code generators for specific languages or frameworks
+- Domain-specific assistants (SQL, legal, finance, etc.)
+- Documentation generators
+- Translation tools
+- And much more
+
+For detailed information about building CLI tools with nGPT, see the [CLI Framework Guide](https://nazdridoy.github.io/ngpt/usage/cli_framework.html) and explore the [CLI Component Examples](https://nazdridoy.github.io/ngpt/examples/cli_components.html).
+
 ## Configuration
 
 ### Command Line Options
@@ -304,17 +353,85 @@ You can configure the client using the following options:
 | `--config` | Path to a custom configuration file or, when used without a value, enters interactive configuration mode |
 | `--config-index` | Index of the configuration to use (default: 0) |
 | `--provider` | Provider name to identify the configuration to use (alternative to --config-index) |
-| `--remove` | Remove the configuration at the specified index (requires --config and --config-index) |
+| `--remove` | Remove the configuration at the specified index (requires --config and --config-index or --provider) |
 | `--show-config` | Show configuration details and exit |
 | `--all` | Used with `--show-config` to display all configurations |
 | `-i, --interactive` | Start an interactive chat session with stylish UI, conversation history, and special commands |
 | `-s, --shell` | Generate and execute shell commands |
 | `-c, --code` | Generate clean code output |
 | `-t, --text` | Open interactive multiline editor for complex prompts |
+| `--language` | Programming language to generate code in (for code mode, default: python) |
+| `--cli-config` | Manage CLI configuration settings (set, get, unset, list, help) |
 | `-v, --version` | Show version information |
 
 For a complete reference of all available options, see the [CLI Usage Guide](https://nazdridoy.github.io/ngpt/usage/cli_usage.html).
 
+### CLI Configuration
+
+NGPT offers a CLI configuration system that allows you to set default values for command-line options:
+
+```bash
+# Set default options
+ngpt --cli-config set language typescript
+ngpt --cli-config set temperature 0.9
+ngpt --cli-config set prettify true
+
+# View current settings
+ngpt --cli-config get
+
+# Get a specific setting
+ngpt --cli-config get language
+
+# Remove a setting
+ngpt --cli-config unset prettify
+
+# List all available options
+ngpt --cli-config list
+
+# Show help information
+ngpt --cli-config help
+```
+
+Key features of CLI configuration:
+- **Context-Aware**: Settings are applied based on the current command mode (e.g., `language` only applies in code generation mode `-c`).
+- **Priority**: When determining option values, NGPT uses the following priority order (highest to lowest):
+  1. Command-line arguments
+  2. Environment variables
+  3. CLI configuration (ngpt-cli.conf)
+  4. Main configuration file (ngpt.conf)
+  5. Default values
+- **Mutual Exclusivity**: For options like `no-stream`, `prettify`, and `stream-prettify`, setting one to `True` automatically sets the others to `False` in the configuration file, ensuring consistency.
+- **Smart Selection**: The `provider` setting is used to select which configuration profile to use, offering a persistent way to select your preferred API.
+
+Available options include:
+- General options (all modes): `provider`, `temperature`, `top_p`, `max_tokens`, `preprompt`, `renderer`, `config-index`, `web-search`
+- Mode-specific options: `language` (code mode only), `log` (interactive and text modes)
+- Mutually exclusive options: `no-stream`, `prettify`, `stream-prettify`
+
+#### Practical Examples
+
+```bash
+# Set Gemini as your default provider
+ngpt --cli-config set provider Gemini
+# Now you can run commands without specifying --provider
+ngpt "Explain quantum computing"
+
+# Configure code generation for TypeScript
+ngpt --cli-config set language typescript
+# Now in code mode, TypeScript will be used by default
+ngpt -c "Write a function to sort an array"
+
+# Set a higher temperature for more creative responses
+ngpt --cli-config set temperature 0.9
+```
+
+The CLI configuration is stored in:
+- Linux: `~/.config/ngpt/ngpt-cli.conf`
+- macOS: `~/Library/Application Support/ngpt/ngpt-cli.conf`
+- Windows: `%APPDATA%\ngpt\ngpt-cli.conf`
+
+For more details, see the [CLI Configuration Guide](https://nazdridoy.github.io/ngpt/usage/cli_config.html).
+
 ### Interactive Configuration
 
 The `--config` option without arguments enters interactive configuration mode, allowing you to add or edit configurations:
@@ -387,10 +504,11 @@ For details on the configuration file format and structure, see the [Configurati
 
 nGPT determines configuration values in the following order (highest priority first):
 
-1. Command line arguments (`--api-key`, `--base-url`, `--model`)
+1. Command line arguments (`--api-key`, `--base-url`, `--model`, etc.)
 2. Environment variables (`OPENAI_API_KEY`, `OPENAI_BASE_URL`, `OPENAI_MODEL`)
-3. Configuration file (selected by `--config-index`, defaults to index 0)
-4. Default values
+3. CLI configuration file (`ngpt-cli.conf`, managed with `--cli-config`)
+4. Main configuration file `ngpt.conf` or `custom-config-file`
+5. Default values
 
 ## Contributing
 

{ngpt-2.7.2 → ngpt-2.9.0}/README.md

@@ -7,6 +7,9 @@
 
 A lightweight Python CLI and library for interacting with OpenAI-compatible APIs, supporting both official and self-hosted LLM endpoints.
 
+![2025-04-23_16-18-01](https://github.com/user-attachments/assets/b8e58926-5165-4352-b48b-9f4a982da86e)
+
+
 ## Table of Contents
 - [Quick Start](#quick-start)
 - [Features](#features)
@@ -16,8 +19,10 @@ A lightweight Python CLI and library for interacting with OpenAI-compatible APIs
   - [Documentation](https://nazdridoy.github.io/ngpt/)
   - [CLI Tool](#as-a-cli-tool)
   - [Python Library](#as-a-library)
+  - [CLI Framework](#as-a-cli-framework)
 - [Configuration](#configuration)
   - [Command Line Options](#command-line-options)
+  - [CLI Configuration](#cli-configuration)
   - [Interactive Configuration](#interactive-configuration)
   - [Configuration File](#configuration-file)
   - [Configuration Priority](#configuration-priority)
@@ -27,11 +32,14 @@ A lightweight Python CLI and library for interacting with OpenAI-compatible APIs
 ## Quick Start
 
 ```bash
-# Install
+# Install with pip
 pip install ngpt
 
-# Install with additional features
-pip install "ngpt[full]"
+# Or install with uv (faster)
+uv pip install ngpt
+
+# Or install globally as a CLI tool (recommended)
+uv tool install ngpt
 
 # Chat with default settings
 ngpt "Tell me about quantum computing"
@@ -77,8 +85,8 @@ For more examples and detailed usage, visit the [CLI Usage Guide](https://nazdri
 
 ## Features
 
-- ✅ **Dual Mode**: Use as a CLI tool or import as a Python library
-- 🪶 **Lightweight**: Minimal dependencies (just `requests`)
+- ✅ **Versatile**: Use as a CLI tool, Python library, or CLI framework for building custom tools
+- 🪶 **Lightweight**: Minimal dependencies with everything you need included
 - 🔄 **API Flexibility**: Works with OpenAI, Ollama, Groq, and any compatible endpoint
 - 💬 **Interactive Chat**: Continuous conversation with memory in modern UI
 - 📊 **Streaming Responses**: Real-time output for better user experience
@@ -91,6 +99,7 @@ For more examples and detailed usage, visit the [CLI Usage Guide](https://nazdri
 - 📝 **Rich Multiline Editor**: Interactive multiline text input with syntax highlighting and intuitive controls
 - 🎭 **System Prompts**: Customize model behavior with custom system prompts
 - 📃 **Conversation Logging**: Save your conversations to text files for later reference
+- 🧰 **CLI Components**: Reusable components for building custom AI-powered command-line tools
 
 See the [Feature Overview](https://nazdridoy.github.io/ngpt/overview.html) for more details.
 
@@ -104,25 +113,25 @@ Key documentation sections:
 - [Installation Guide](https://nazdridoy.github.io/ngpt/installation.html)
 - [CLI Usage Guide](https://nazdridoy.github.io/ngpt/usage/cli_usage.html)
 - [Library Usage Guide](https://nazdridoy.github.io/ngpt/usage/library_usage.html)
+- [CLI Framework Guide](https://nazdridoy.github.io/ngpt/usage/cli_framework.html)
 - [Configuration Guide](https://nazdridoy.github.io/ngpt/configuration.html)
 - [Examples & Tutorials](https://nazdridoy.github.io/ngpt/examples/basic.html)
 
 ## Installation
 
 ```bash
-# Basic installation (minimal dependencies)
+# Installation with pip
 pip install ngpt
 
-# Full installation with all features (recommended)
-pip install "ngpt[full]"
+# Or install with uv (faster installation)
+uv pip install ngpt
+
+# Or install globally as a CLI tool (recommended for command-line usage)
+uv tool install ngpt
 ```
 
 Requires Python 3.8 or newer.
 
-The full installation includes:
-- Enhanced markdown rendering with syntax highlighting
-- Improved interactive input experience with multiline editing
-
 For detailed installation instructions, see the [Installation Guide](https://nazdridoy.github.io/ngpt/installation.html).
 
 ## Usage
@@ -242,6 +251,47 @@ print(code)
 
 For advanced usage patterns and integrations, check out the [Advanced Examples](https://nazdridoy.github.io/ngpt/examples/advanced.html).
 
+### As a CLI Framework
+
+nGPT can also be used as a framework to build your own AI-powered command-line tools. You can leverage nGPT's pre-built CLI components to quickly develop sophisticated CLI applications.
+
+```python
+from ngpt import NGPTClient, load_config
+from ngpt.cli import interactive_chat_session, prettify_markdown, ColoredHelpFormatter
+import argparse
+
+# Create a custom CLI tool with colorized help
+parser = argparse.ArgumentParser(
+    description="Specialized Code Assistant",
+    formatter_class=ColoredHelpFormatter
+)
+parser.add_argument("prompt", nargs="?", help="Code description")
+parser.add_argument("--language", "-l", default="python", help="Programming language")
+parser.add_argument("--interactive", "-i", action="store_true", help="Start interactive mode")
+args = parser.parse_args()
+
+# Initialize client
+client = NGPTClient(**load_config())
+
+# Use interactive session for conversation
+if args.interactive:
+    system_prompt = f"You are an expert {args.language} developer. Provide clear, detailed answers."
+    interactive_chat_session(client=client, preprompt=system_prompt, prettify=True)
+elif args.prompt:
+    # Generate and prettify code
+    code = client.generate_code(args.prompt, language=args.language)
+    print(prettify_markdown(f"```{args.language}\n{code}\n```"))
+```
+
+This allows you to build specialized AI tools like:
+- Code generators for specific languages or frameworks
+- Domain-specific assistants (SQL, legal, finance, etc.)
+- Documentation generators
+- Translation tools
+- And much more
+
+For detailed information about building CLI tools with nGPT, see the [CLI Framework Guide](https://nazdridoy.github.io/ngpt/usage/cli_framework.html) and explore the [CLI Component Examples](https://nazdridoy.github.io/ngpt/examples/cli_components.html).
+
 ## Configuration
 
 ### Command Line Options
@@ -268,17 +318,85 @@ You can configure the client using the following options:
 | `--config` | Path to a custom configuration file or, when used without a value, enters interactive configuration mode |
 | `--config-index` | Index of the configuration to use (default: 0) |
 | `--provider` | Provider name to identify the configuration to use (alternative to --config-index) |
-| `--remove` | Remove the configuration at the specified index (requires --config and --config-index) |
+| `--remove` | Remove the configuration at the specified index (requires --config and --config-index or --provider) |
 | `--show-config` | Show configuration details and exit |
 | `--all` | Used with `--show-config` to display all configurations |
 | `-i, --interactive` | Start an interactive chat session with stylish UI, conversation history, and special commands |
 | `-s, --shell` | Generate and execute shell commands |
 | `-c, --code` | Generate clean code output |
 | `-t, --text` | Open interactive multiline editor for complex prompts |
+| `--language` | Programming language to generate code in (for code mode, default: python) |
+| `--cli-config` | Manage CLI configuration settings (set, get, unset, list, help) |
 | `-v, --version` | Show version information |
 
 For a complete reference of all available options, see the [CLI Usage Guide](https://nazdridoy.github.io/ngpt/usage/cli_usage.html).
 
+### CLI Configuration
+
+NGPT offers a CLI configuration system that allows you to set default values for command-line options:
+
+```bash
+# Set default options
+ngpt --cli-config set language typescript
+ngpt --cli-config set temperature 0.9
+ngpt --cli-config set prettify true
+
+# View current settings
+ngpt --cli-config get
+
+# Get a specific setting
+ngpt --cli-config get language
+
+# Remove a setting
+ngpt --cli-config unset prettify
+
+# List all available options
+ngpt --cli-config list
+
+# Show help information
+ngpt --cli-config help
+```
+
+Key features of CLI configuration:
+- **Context-Aware**: Settings are applied based on the current command mode (e.g., `language` only applies in code generation mode `-c`).
+- **Priority**: When determining option values, NGPT uses the following priority order (highest to lowest):
+  1. Command-line arguments
+  2. Environment variables
+  3. CLI configuration (ngpt-cli.conf)
+  4. Main configuration file (ngpt.conf)
+  5. Default values
+- **Mutual Exclusivity**: For options like `no-stream`, `prettify`, and `stream-prettify`, setting one to `True` automatically sets the others to `False` in the configuration file, ensuring consistency.
+- **Smart Selection**: The `provider` setting is used to select which configuration profile to use, offering a persistent way to select your preferred API.
+
+Available options include:
+- General options (all modes): `provider`, `temperature`, `top_p`, `max_tokens`, `preprompt`, `renderer`, `config-index`, `web-search`
+- Mode-specific options: `language` (code mode only), `log` (interactive and text modes)
+- Mutually exclusive options: `no-stream`, `prettify`, `stream-prettify`
+
+#### Practical Examples
+
+```bash
+# Set Gemini as your default provider
+ngpt --cli-config set provider Gemini
+# Now you can run commands without specifying --provider
+ngpt "Explain quantum computing"
+
+# Configure code generation for TypeScript
+ngpt --cli-config set language typescript
+# Now in code mode, TypeScript will be used by default
+ngpt -c "Write a function to sort an array"
+
+# Set a higher temperature for more creative responses
+ngpt --cli-config set temperature 0.9
+```
+
+The CLI configuration is stored in:
+- Linux: `~/.config/ngpt/ngpt-cli.conf`
+- macOS: `~/Library/Application Support/ngpt/ngpt-cli.conf`
+- Windows: `%APPDATA%\ngpt\ngpt-cli.conf`
+
+For more details, see the [CLI Configuration Guide](https://nazdridoy.github.io/ngpt/usage/cli_config.html).
+
 ### Interactive Configuration
 
 The `--config` option without arguments enters interactive configuration mode, allowing you to add or edit configurations:
@@ -351,10 +469,11 @@ For details on the configuration file format and structure, see the [Configurati
 
 nGPT determines configuration values in the following order (highest priority first):
 
-1. Command line arguments (`--api-key`, `--base-url`, `--model`)
+1. Command line arguments (`--api-key`, `--base-url`, `--model`, etc.)
 2. Environment variables (`OPENAI_API_KEY`, `OPENAI_BASE_URL`, `OPENAI_MODEL`)
-3. Configuration file (selected by `--config-index`, defaults to index 0)
-4. Default values
+3. CLI configuration file (`ngpt-cli.conf`, managed with `--cli-config`)
+4. Main configuration file `ngpt.conf` or `custom-config-file`
+5. Default values
 
 ## Contributing
 

{ngpt-2.7.2 → ngpt-2.9.0}/docs/README.md

@@ -1,21 +1,28 @@
 # nGPT Documentation
 
-Welcome to the documentation for nGPT, a lightweight Python CLI and library for interacting with OpenAI-compatible APIs, supporting both official and self-hosted LLM endpoints.
+Welcome to the documentation for nGPT, a lightweight Python CLI and library for interacting with OpenAI-compatible APIs, supporting both official and self-hosted LLM endpoints. nGPT offers three main modes of use:
+
+- A command-line interface (CLI) tool for quick AI interactions
+- A Python library for integration into your applications
+- A CLI framework for building your own AI-powered command-line tools
 
 ## Table of Contents
 
 - [Overview](overview.md)
 - [Installation](installation.md)
 - [Usage](usage/README.md)
-  - [Library Usage](usage/library_usage.md)
   - [CLI Usage](usage/cli_usage.md)
+  - [Library Usage](usage/library_usage.md)
+  - [CLI Framework](usage/cli_framework.md)
 - [API Reference](api/README.md)
   - [NGPTClient](api/client.md)
   - [Configuration](api/config.md)
+  - [CLI Components](api/cli.md)
 - [Examples](examples/README.md)
   - [Basic Examples](examples/basic.md)
   - [Advanced Examples](examples/advanced.md)
   - [Custom Integrations](examples/integrations.md)
+  - [CLI Component Examples](examples/cli_components.md)
 - [Configuration](configuration.md)
 - [Contributing](CONTRIBUTING.md)
 - [License](LICENSE.md)
@@ -24,4 +31,6 @@ Welcome to the documentation for nGPT, a lightweight Python CLI and library for
 
 For a quick start, refer to the [Installation](installation.md) and [Usage](usage/README.md) guides.
 
-If you're primarily interested in using nGPT as a library in your Python projects, head directly to the [Library Usage](usage/library_usage.md) guide. 
+If you're primarily interested in using nGPT as a library in your Python projects, head directly to the [Library Usage](usage/library_usage.md) guide.
+
+For creating your own CLI tools using nGPT's components, check out the [CLI Framework](usage/cli_framework.md) guide and the [CLI Component Examples](examples/cli_components.md).