ngpt 2.0.0__tar.gz → 2.1.0__tar.gz

{ngpt-2.0.0 → ngpt-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ngpt
-Version: 2.0.0
+Version: 2.1.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
@@ -37,14 +37,17 @@ Description-Content-Type: text/markdown
 [![PyPI version](https://img.shields.io/pypi/v/ngpt.svg)](https://pypi.org/project/ngpt/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Python Versions](https://img.shields.io/pypi/pyversions/ngpt.svg)](https://pypi.org/project/ngpt/)
+[![Documentation](https://img.shields.io/badge/docs-available-brightgreen.svg)](https://nazdridoy.github.io/ngpt/)
 
 A lightweight Python CLI and library for interacting with OpenAI-compatible APIs, supporting both official and self-hosted LLM endpoints.
 
 ## Table of Contents
 - [Quick Start](#quick-start)
 - [Features](#features)
+- [Documentation](#documentation)
 - [Installation](#installation)
 - [Usage](#usage)
+  - [Documentation](https://nazdridoy.github.io/ngpt/)
   - [CLI Tool](#as-a-cli-tool)
   - [Python Library](#as-a-library)
 - [Configuration](#configuration)
@@ -93,6 +96,12 @@ ngpt --text
 - 🧩 **Clean Code Generation**: Output code without markdown or explanations
 - 📝 **Rich Multiline Editor**: Interactive multiline text input with syntax highlighting and intuitive controls
 
+## Documentation
+
+Comprehensive documentation, including API reference, usage guides, and examples, is available at:
+
+**[https://nazdridoy.github.io/ngpt/](https://nazdridoy.github.io/ngpt/)**
+
 ## Installation
 
 ```bash
@@ -220,6 +229,9 @@ You can configure the client using the following options:
 | `--list-models` | List all available models for the selected configuration (can be combined with --config-index) |
 | `--web-search` | Enable web search capability |
 | `-n, --no-stream` | Return the whole response without streaming |
+| `--temperature` | Set temperature (controls randomness, default: 0.7) |
+| `--top_p` | Set top_p (controls diversity, default: 1.0) |
+| `--max_length` | Set maximum response length in tokens |
 | `--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) |
 | `--remove` | Remove the configuration at the specified index (requires --config and --config-index) |

{ngpt-2.0.0 → ngpt-2.1.0}/README.md

@@ -3,14 +3,17 @@
 [![PyPI version](https://img.shields.io/pypi/v/ngpt.svg)](https://pypi.org/project/ngpt/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Python Versions](https://img.shields.io/pypi/pyversions/ngpt.svg)](https://pypi.org/project/ngpt/)
+[![Documentation](https://img.shields.io/badge/docs-available-brightgreen.svg)](https://nazdridoy.github.io/ngpt/)
 
 A lightweight Python CLI and library for interacting with OpenAI-compatible APIs, supporting both official and self-hosted LLM endpoints.
 
 ## Table of Contents
 - [Quick Start](#quick-start)
 - [Features](#features)
+- [Documentation](#documentation)
 - [Installation](#installation)
 - [Usage](#usage)
+  - [Documentation](https://nazdridoy.github.io/ngpt/)
   - [CLI Tool](#as-a-cli-tool)
   - [Python Library](#as-a-library)
 - [Configuration](#configuration)
@@ -59,6 +62,12 @@ ngpt --text
 - 🧩 **Clean Code Generation**: Output code without markdown or explanations
 - 📝 **Rich Multiline Editor**: Interactive multiline text input with syntax highlighting and intuitive controls
 
+## Documentation
+
+Comprehensive documentation, including API reference, usage guides, and examples, is available at:
+
+**[https://nazdridoy.github.io/ngpt/](https://nazdridoy.github.io/ngpt/)**
+
 ## Installation
 
 ```bash
@@ -186,6 +195,9 @@ You can configure the client using the following options:
 | `--list-models` | List all available models for the selected configuration (can be combined with --config-index) |
 | `--web-search` | Enable web search capability |
 | `-n, --no-stream` | Return the whole response without streaming |
+| `--temperature` | Set temperature (controls randomness, default: 0.7) |
+| `--top_p` | Set top_p (controls diversity, default: 1.0) |
+| `--max_length` | Set maximum response length in tokens |
 | `--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) |
 | `--remove` | Remove the configuration at the specified index (requires --config and --config-index) |

ngpt-2.1.0/docs/CONTRIBUTING.md

@@ -0,0 +1,93 @@
+---
+---
+
+# Contributing to NGPT
+
+Thank you for your interest in contributing to NGPT! This document provides guidelines and instructions for contributing to this project.
+
+## Development Setup
+
+1. Fork the repository
+2. Clone your fork: `git clone https://github.com/YOUR_USERNAME/ngpt.git`
+3. Navigate to the project directory: `cd ngpt`
+4. Set up Python environment:
+   - It's recommended to use a virtual environment
+   - Create a virtual environment: `python -m venv .venv`
+   - Activate the virtual environment:
+     - Windows: `.venv\Scripts\activate`
+     - Unix/MacOS: `source .venv/bin/activate`
+5. Install dependencies: `pip install -e .` 
+6. Open the project in your preferred code editor
+
+## Code Structure
+
+- `ngpt/` - Main package directory
+  - `__init__.py` - Package initialization
+  - `cli.py` - Command-line interface implementation
+  - `config.py` - Configuration management
+  - `client.py` - Client implementation
+- `.github/` - GitHub workflows and templates
+- `pyproject.toml` - Project configuration and dependencies
+
+## Code Style Guidelines
+
+- Follow PEP 8 style guidelines for Python code
+- Use consistent indentation (4 spaces)
+- Write descriptive docstrings for functions and classes
+- Add type hints where appropriate
+- Add comments for complex logic
+
+## Pull Request Guidelines
+
+Before submitting a pull request, please make sure that:
+  
+- Your code follows the project's coding conventions
+- You have tested your changes thoroughly
+- All existing tests pass (if applicable)
+- The commit messages are clear and follow conventional commit guidelines as specified in [COMMIT_GUIDELINES.md](COMMIT_GUIDELINES.md)
+- You have provided a detailed explanation of the changes in the pull request description
+
+## Submitting Changes
+
+1. Create a new branch: `git checkout -b feature/your-feature-name`
+2. Make your changes
+3. Test thoroughly
+4. Commit with clear messages: `git commit -m "feat: description"`
+5. Push to your fork: `git push origin feature/your-feature-name`
+6. Open a Pull Request against the main repository
+
+## Testing
+
+Before submitting your changes, please test:
+
+- Basic functionality
+- Any new features you've added
+- Any components you've modified
+- Ensure all tests pass if there's a test suite
+
+## Issue Reporting
+
+When opening an issue, please:
+
+- Use a clear and descriptive title
+- Provide a detailed description of the issue, including the environment and steps to reproduce
+- Include any relevant logs or code snippets
+- Specify your Python version and operating system
+- Search the repository for similar issues before creating a new one
+
+## Feature Requests
+
+Feature requests are welcome! To submit a feature request:
+
+- Use a clear and descriptive title
+- Provide a detailed description of the proposed feature
+- Explain why this feature would be useful to NGPT users
+- If possible, suggest how it might be implemented
+
+## Questions and Discussions
+
+For questions about the project that aren't bugs or feature requests, please use GitHub Discussions instead of opening an issue. This helps keep the issue tracker focused on bugs and features.
+
+## License
+
+By contributing to this project, you agree that your contributions will be licensed under the same [LICENSE](LICENSE) as the project.

ngpt-2.1.0/docs/LICENSE.md

@@ -0,0 +1,24 @@
+---
+---
+
+MIT License
+
+Copyright (c) 2025 nazdridoy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ngpt-2.1.0/docs/README.md

@@ -0,0 +1,27 @@
+# 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.
+
+## 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)
+- [API Reference](api/README.md)
+  - [NGPTClient](api/client.md)
+  - [Configuration](api/config.md)
+- [Examples](examples/README.md)
+  - [Basic Examples](examples/basic.md)
+  - [Advanced Examples](examples/advanced.md)
+  - [Custom Integrations](examples/integrations.md)
+- [Configuration](configuration.md)
+- [Contributing](CONTRIBUTING.md)
+- [License](LICENSE.md)
+
+## Getting Started
+
+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. 

ngpt-2.1.0/docs/_config.yml

@@ -0,0 +1,7 @@
+title: nGPT Documentation
+description: A lightweight Python CLI and library for interacting with OpenAI-compatible APIs
+baseurl: /ngpt
+remote_theme: pages-themes/hacker
+plugins:
+  - jekyll-remote-theme
+show_downloads: false 

ngpt-2.1.0/docs/api/README.md

@@ -0,0 +1,47 @@
+# API Reference
+
+This section provides detailed documentation for the nGPT API, including all classes, methods, functions, and parameters.
+
+## Overview
+
+nGPT's API consists of two main components:
+
+1. **NGPTClient**: The main client class used to interact with AI providers
+2. **Configuration Utilities**: Functions for managing configuration files and settings
+
+## Table of Contents
+
+- [NGPTClient](client.md) - Primary client for interacting with LLM APIs
+  - [Initialization](client.md#initialization)
+  - [Chat Method](client.md#chat-method)
+  - [Generate Shell Command](client.md#generate-shell-command)
+  - [Generate Code](client.md#generate-code)
+  - [List Models](client.md#list-models)
+
+- [Configuration](config.md) - Functions for managing configurations
+  - [Loading Configurations](config.md#loading-configurations)
+  - [Creating Configurations](config.md#creating-configurations)
+  - [Editing Configurations](config.md#editing-configurations)
+  - [Removing Configurations](config.md#removing-configurations)
+  - [Configuration Paths](config.md#configuration-paths)
+
+## Quick Reference
+
+```python
+# Import core components
+from ngpt import NGPTClient, load_config
+
+# Import configuration utilities
+from ngpt.config import (
+    load_configs,
+    get_config_path,
+    get_config_dir,
+    add_config_entry,
+    remove_config_entry
+)
+
+# Import version information
+from ngpt import __version__
+```
+
+For complete documentation on using these components, see the linked reference pages. 

ngpt-2.1.0/docs/api/client.md

@@ -0,0 +1,263 @@
+# NGPTClient
+
+`NGPTClient` is the primary class for interacting with OpenAI-compatible APIs. It provides methods for chat completion, code generation, shell command generation, and model listing.
+
+## Initialization
+
+```python
+from ngpt import NGPTClient
+
+client = NGPTClient(
+    api_key: str = "",
+    base_url: str = "https://api.openai.com/v1/",
+    provider: str = "OpenAI",
+    model: str = "gpt-3.5-turbo"
+)
+```
+
+### Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `api_key` | `str` | `""` | API key for authentication |
+| `base_url` | `str` | `"https://api.openai.com/v1/"` | Base URL for the API endpoint |
+| `provider` | `str` | `"OpenAI"` | Name of the provider (for reference only) |
+| `model` | `str` | `"gpt-3.5-turbo"` | Default model to use for completion |
+
+### Examples
+
+```python
+# Basic initialization with OpenAI
+client = NGPTClient(api_key="your-openai-api-key")
+
+# Using a different provider
+client = NGPTClient(
+    api_key="your-api-key",
+    base_url="https://api.groq.com/openai/v1/",
+    provider="Groq",
+    model="llama3-70b-8192"
+)
+
+# Using a local Ollama instance
+client = NGPTClient(
+    api_key="",  # No key needed for local Ollama
+    base_url="http://localhost:11434/v1/",
+    provider="Ollama-Local",
+    model="llama3"
+)
+```
+
+## Chat Method
+
+The primary method for interacting with the AI model.
+
+```python
+response = client.chat(
+    prompt: str,
+    stream: bool = True,
+    temperature: float = 0.7,
+    max_tokens: Optional[int] = None,
+    messages: Optional[List[Dict[str, str]]] = None,
+    web_search: bool = False,
+    **kwargs
+) -> str
+```
+
+### Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `prompt` | `str` | Required | The user's message |
+| `stream` | `bool` | `True` | Whether to stream the response |
+| `temperature` | `float` | `0.7` | Controls randomness in the response (0.0-1.0) |
+| `max_tokens` | `Optional[int]` | `None` | Maximum number of tokens to generate |
+| `messages` | `Optional[List[Dict[str, str]]]` | `None` | Optional list of message objects for conversation history |
+| `web_search` | `bool` | `False` | Whether to enable web search capability |
+| `**kwargs` | | | Additional arguments to pass to the API |
+
+### Returns
+
+- When `stream=False`: A string containing the complete response
+- When `stream=True`: A generator yielding response chunks that can be iterated over
+
+### Examples
+
+```python
+# Basic chat with streaming
+for chunk in client.chat("Tell me about quantum computing"):
+    print(chunk, end="", flush=True)
+print()  # Final newline
+
+# Without streaming
+response = client.chat("Tell me about quantum computing", stream=False)
+print(response)
+
+# With conversation history
+messages = [
+    {"role": "system", "content": "You are a helpful assistant."},
+    {"role": "user", "content": "Hello, who are you?"},
+    {"role": "assistant", "content": "I'm an AI assistant. How can I help you today?"},
+    {"role": "user", "content": "Tell me about yourself"}
+]
+response = client.chat("", messages=messages)
+print(response)
+
+# With web search
+response = client.chat("What's the latest news about AI?", web_search=True)
+print(response)
+
+# With temperature control
+response = client.chat("Write a creative story", temperature=0.9)  # More random
+response = client.chat("Explain how a CPU works", temperature=0.2)  # More focused
+
+# With token limit
+response = client.chat("Summarize this concept", max_tokens=100)
+```
+
+## Generate Shell Command
+
+Generates a shell command based on the prompt, optimized for the user's operating system.
+
+```python
+command = client.generate_shell_command(
+    prompt: str,
+    web_search: bool = False
+) -> str
+```
+
+### Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `prompt` | `str` | Required | Description of the command to generate |
+| `web_search` | `bool` | `False` | Whether to enable web search capability |
+
+### Returns
+
+A string containing the generated shell command appropriate for the user's OS.
+
+### Examples
+
+```python
+# Generate a command to find large files
+command = client.generate_shell_command("find all files larger than 100MB")
+print(f"Generated command: {command}")
+
+# Execute the generated command
+import subprocess
+result = subprocess.run(command, shell=True, capture_output=True, text=True)
+print(f"Output: {result.stdout}")
+
+# With web search for more current command syntax
+command = client.generate_shell_command(
+    "show Docker container resource usage in a nice format",
+    web_search=True
+)
+```
+
+## Generate Code
+
+Generates clean code based on the prompt, without markdown formatting or explanations.
+
+```python
+code = client.generate_code(
+    prompt: str,
+    language: str = "python",
+    web_search: bool = False
+) -> str
+```
+
+### Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `prompt` | `str` | Required | Description of the code to generate |
+| `language` | `str` | `"python"` | Programming language to generate code in |
+| `web_search` | `bool` | `False` | Whether to enable web search capability |
+
+### Returns
+
+A string containing the generated code without any markdown formatting or explanations.
+
+### Examples
+
+```python
+# Generate Python code (default)
+python_code = client.generate_code("function to calculate fibonacci numbers")
+print(python_code)
+
+# Generate JavaScript code
+js_code = client.generate_code(
+    "function to validate email addresses using regex",
+    language="javascript"
+)
+print(js_code)
+
+# Generate code with web search for latest best practices
+react_code = client.generate_code(
+    "create a React component that fetches and displays data from an API",
+    language="jsx",
+    web_search=True
+)
+```
+
+## List Models
+
+Retrieves the list of available models from the API.
+
+```python
+models = client.list_models() -> list
+```
+
+### Returns
+
+A list of available model objects or an empty list if the request failed.
+
+### Examples
+
+```python
+# Get available models
+models = client.list_models()
+
+# Print model IDs
+if models:
+    print("Available models:")
+    for model in models:
+        print(f"- {model.get('id')}")
+else:
+    print("No models available or could not retrieve models")
+
+# Filter for specific models
+gpt4_models = [m for m in models if "gpt-4" in m.get('id', '')]
+for model in gpt4_models:
+    print(f"GPT-4 model: {model.get('id')}")
+```
+
+## Error Handling
+
+The `NGPTClient` methods include basic error handling for common issues:
+
+- HTTP errors (401, 404, 429, etc.)
+- Connection errors
+- Timeout errors
+- JSON parsing errors
+
+For production code, it's recommended to implement your own error handling:
+
+```python
+import requests
+
+try:
+    response = client.chat("Tell me about quantum computing")
+except requests.exceptions.HTTPError as e:
+    if e.response.status_code == 401:
+        print("Authentication failed. Check your API key.")
+    elif e.response.status_code == 429:
+        print("Rate limit exceeded. Please wait and try again.")
+    else:
+        print(f"HTTP error: {e}")
+except requests.exceptions.ConnectionError:
+    print("Connection error. Check your internet and base URL.")
+except Exception as e:
+    print(f"An unexpected error occurred: {e}")
+```