yaicli 0.1.0__tar.gz → 0.3.0__tar.gz

{yaicli-0.1.0 → yaicli-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: yaicli
-Version: 0.1.0
+Version: 0.3.0
 Summary: A simple CLI tool to interact with LLM
 Project-URL: Homepage, https://github.com/belingud/yaicli
 Project-URL: Repository, https://github.com/belingud/yaicli
@@ -222,19 +222,21 @@ Requires-Dist: socksio>=1.0.0
 Requires-Dist: typer>=0.15.2
 Description-Content-Type: text/markdown
 
-# YAICLI - Your AI Command Line Interface
+# YAICLI: Your AI assistant in the command line.
 
 [![PyPI version](https://img.shields.io/pypi/v/yaicli?style=for-the-badge)](https://pypi.org/project/yaicli/)
 ![GitHub License](https://img.shields.io/github/license/belingud/yaicli?style=for-the-badge)
 ![PyPI - Downloads](https://img.shields.io/pypi/dm/yaicli?logo=pypi&style=for-the-badge)
 ![Pepy Total Downloads](https://img.shields.io/pepy/dt/yaicli?style=for-the-badge&logo=python)
 
-YAICLI is a powerful yet lightweight command-line AI assistant that brings the capabilities of Large Language Models (LLMs) like GPT-4o directly to your terminal. Interact with AI through multiple modes: have natural conversations, generate and execute shell commands, or get quick answers without leaving your workflow.
+YAICLI is a powerful yet lightweight command-line AI assistant that brings the capabilities of Large Language Models (
+LLMs) like GPT-4o directly to your terminal. Interact with AI through multiple modes: have natural conversations,
+generate and execute shell commands, or get quick answers without leaving your workflow.
 
 **Supports both standard and deep reasoning models across all major LLM providers.**
 
 <p align="center">
-  <img src="https://vhs.charm.sh/vhs-5U1BBjJkTUBReRswsSgIVx.gif" alt="YAICLI Demo" width="85%">
+  <img src="https://vhs.charm.sh/vhs-5U1BBjJkTUBReRswsSgIVx.gif" alt="YAICLI Chat Demo" width="85%">
 </p>
 
 > [!NOTE]
@@ -243,30 +245,37 @@ YAICLI is a powerful yet lightweight command-line AI assistant that brings the c
 ## ✨ Key Features
 
 ### 🔄 Multiple Interaction Modes
+
 - **💬 Chat Mode**: Engage in persistent conversations with full context tracking
 - **🚀 Execute Mode**: Generate and safely run OS-specific shell commands
 - **⚡ Quick Query**: Get instant answers without entering interactive mode
 
 ### 🧠 Smart Environment Awareness
+
 - **Auto-detection**: Identifies your shell (bash/zsh/PowerShell/CMD) and OS
 - **Safe Command Execution**: 3-step verification before running any command
 - **Flexible Input**: Pipe content directly (`cat log.txt | ai "analyze this"`)
 
 ### 🔌 Universal LLM Compatibility
+
 - **OpenAI-Compatible**: Works with any OpenAI-compatible API endpoint
 - **Multi-Provider Support**: Easy configuration for Claude, Gemini, Cohere, etc.
 - **Custom Response Parsing**: Extract exactly what you need with jmespath
 
 ### 💻 Enhanced Terminal Experience
+
 - **Real-time Streaming**: See responses as they're generated with cursor animation
 - **Rich History Management**: LRU-based history with 500 entries by default
 - **Syntax Highlighting**: Beautiful code formatting with customizable themes
 
 ### 🛠️ Developer-Friendly
+
 - **Layered Configuration**: Environment variables > Config file > Sensible defaults
 - **Debugging Tools**: Verbose mode with detailed API tracing
 - **Lightweight**: Minimal dependencies with focused functionality
 
+![What is life](artwork/reasoning_example.png)
+
 ## 📦 Installation
 
 ### Prerequisites
@@ -306,77 +315,94 @@ YAICLI uses a simple configuration file to store your preferences and API keys.
 
 ### Configuration File Structure
 
-The default configuration file is located at `~/.config/yaicli/config.ini`. You can use `ai --template` to see default settings, just as below:
+The default configuration file is located at `~/.config/yaicli/config.ini`. You can use `ai --template` to see default
+settings, just as below:
 
 ```ini
 [core]
-PROVIDER=openai
-BASE_URL=https://api.openai.com/v1
-API_KEY=
-MODEL=gpt-4o
+PROVIDER = openai
+BASE_URL = https://api.openai.com/v1
+API_KEY =
+MODEL = gpt-4o
 
 # auto detect shell and os (or specify manually, e.g., bash, zsh, powershell.exe)
-SHELL_NAME=auto
-OS_NAME=auto
+SHELL_NAME = auto
+OS_NAME = auto
 
 # API paths (usually no need to change for OpenAI compatible APIs)
-COMPLETION_PATH=chat/completions
-ANSWER_PATH=choices[0].message.content
+COMPLETION_PATH = chat/completions
+ANSWER_PATH = choices[0].message.content
 
 # true: streaming response, false: non-streaming
-STREAM=true
+STREAM = true
 
 # LLM parameters
-TEMPERATURE=0.7
-TOP_P=1.0
-MAX_TOKENS=1024
-TIMEOUT=60
+TEMPERATURE = 0.7
+TOP_P = 1.0
+MAX_TOKENS = 1024
+TIMEOUT = 60
 
 # Interactive mode parameters
-INTERACTIVE_ROUND=25
+INTERACTIVE_ROUND = 25
 
 # UI/UX
-CODE_THEME=monokai
-MAX_HISTORY=500 # Max entries kept in history file
-AUTO_SUGGEST=true
+CODE_THEME = monokai
+# Max entries kept in history file
+MAX_HISTORY = 500
+AUTO_SUGGEST = true
+# Print reasoning content or not
+SHOW_REASONING = true
+# Text alignment (default, left, center, right, full)
+JUSTIFY = default
+
+# Chat history settings
+CHAT_HISTORY_DIR = <tempdir>/yaicli/chats
+MAX_SAVED_CHATS = 20
 ```
 
 ### Configuration Options Reference
 
-| Option | Description | Default | Env Variable |
-|--------|-------------|---------|---------------|
-| `BASE_URL` | API endpoint URL | `https://api.openai.com/v1` | `YAI_BASE_URL` |
-| `API_KEY` | Your API key | - | `YAI_API_KEY` |
-| `MODEL` | LLM model to use | `gpt-4o` | `YAI_MODEL` |
-| `SHELL_NAME` | Shell type | `auto` | `YAI_SHELL_NAME` |
-| `OS_NAME` | Operating system | `auto` | `YAI_OS_NAME` |
-| `COMPLETION_PATH` | API completion path | `chat/completions` | `YAI_COMPLETION_PATH` |
-| `ANSWER_PATH` | JSON path for response | `choices[0].message.content` | `YAI_ANSWER_PATH` |
-| `STREAM` | Enable streaming | `true` | `YAI_STREAM` |
-| `TIMEOUT` | API timeout (seconds) | `60` | `YAI_TIMEOUT` |
-| `INTERACTIVE_ROUND` | Interactive mode rounds | `25` | `YAI_INTERACTIVE_ROUND` |
-| `CODE_THEME` | Syntax highlighting theme | `monokai` | `YAI_CODE_THEME` |
-| `TEMPERATURE` | Response randomness | `0.7` | `YAI_TEMPERATURE` |
-| `TOP_P` | Top-p sampling | `1.0` | `YAI_TOP_P` |
-| `MAX_TOKENS` | Max response tokens | `1024` | `YAI_MAX_TOKENS` |
-| `MAX_HISTORY` | Max history entries | `500` | `YAI_MAX_HISTORY` |
-| `AUTO_SUGGEST` | Enable history suggestions | `true` | `YAI_AUTO_SUGGEST` |
+| Option              | Description                                 | Default                      | Env Variable            |
+|---------------------|---------------------------------------------|------------------------------|-------------------------|
+| `PROVIDER`          | LLM provider (openai, claude, cohere, etc.) | `openai`                     | `YAI_PROVIDER`          |
+| `BASE_URL`          | API endpoint URL                            | `https://api.openai.com/v1`  | `YAI_BASE_URL`          |
+| `API_KEY`           | Your API key                                | -                            | `YAI_API_KEY`           |
+| `MODEL`             | LLM model to use                            | `gpt-4o`                     | `YAI_MODEL`             |
+| `SHELL_NAME`        | Shell type                                  | `auto`                       | `YAI_SHELL_NAME`        |
+| `OS_NAME`           | Operating system                            | `auto`                       | `YAI_OS_NAME`           |
+| `COMPLETION_PATH`   | API completion path                         | `chat/completions`           | `YAI_COMPLETION_PATH`   |
+| `ANSWER_PATH`       | JSON path for response                      | `choices[0].message.content` | `YAI_ANSWER_PATH`       |
+| `STREAM`            | Enable streaming                            | `true`                       | `YAI_STREAM`            |
+| `TIMEOUT`           | API timeout (seconds)                       | `60`                         | `YAI_TIMEOUT`           |
+| `INTERACTIVE_ROUND` | Interactive mode rounds                     | `25`                         | `YAI_INTERACTIVE_ROUND` |
+| `CODE_THEME`        | Syntax highlighting theme                   | `monokai`                    | `YAI_CODE_THEME`        |
+| `TEMPERATURE`       | Response randomness                         | `0.7`                        | `YAI_TEMPERATURE`       |
+| `TOP_P`             | Top-p sampling                              | `1.0`                        | `YAI_TOP_P`             |
+| `MAX_TOKENS`        | Max response tokens                         | `1024`                       | `YAI_MAX_TOKENS`        |
+| `MAX_HISTORY`       | Max history entries                         | `500`                        | `YAI_MAX_HISTORY`       |
+| `AUTO_SUGGEST`      | Enable history suggestions                  | `true`                       | `YAI_AUTO_SUGGEST`      |
+| `SHOW_REASONING`    | Enable reasoning display                    | `true`                       | `YAI_SHOW_REASONING`    |
+| `JUSTIFY`           | Text alignment                              | `default`                    | `YAI_JUSTIFY`           |
+| `CHAT_HISTORY_DIR`  | Chat history directory                      | `<tempdir>/yaicli/history`   | `YAI_CHAT_HISTORY_DIR`  |
+| `MAX_SAVED_CHATS`   | Max saved chats                             | `20`                         | `YAI_MAX_SAVED_CHATS`   |
 
 ### LLM Provider Configuration
 
-YAICLI works with all major LLM providers. The default configuration is set up for OpenAI, but you can easily switch to other providers.
+YAICLI works with all major LLM providers. The default configuration is set up for OpenAI, but you can easily switch to
+other providers.
 
 #### Pre-configured Provider Settings
 
-| Provider | BASE_URL | COMPLETION_PATH | ANSWER_PATH |
-|----------|----------|-----------------|-------------|
-| **OpenAI** (default) | `https://api.openai.com/v1` | `chat/completions` | `choices[0].message.content` |
-| **Claude** (native API) | `https://api.anthropic.com/v1` | `messages` | `content[0].text` |
-| **Claude** (OpenAI-compatible) | `https://api.anthropic.com/v1/openai` | `chat/completions` | `choices[0].message.content` |
-| **Cohere** | `https://api.cohere.com/v2` | `chat` | `message.content[0].text` |
-| **Google Gemini** | `https://generativelanguage.googleapis.com/v1beta/openai` | `chat/completions` | `choices[0].message.content` |
+| Provider                       | BASE_URL                                                  | COMPLETION_PATH    | ANSWER_PATH                  |
+|--------------------------------|-----------------------------------------------------------|--------------------|------------------------------|
+| **OpenAI** (default)           | `https://api.openai.com/v1`                               | `chat/completions` | `choices[0].message.content` |
+| **Claude** (native API)        | `https://api.anthropic.com/v1`                            | `messages`         | `content[0].text`            |
+| **Claude** (OpenAI-compatible) | `https://api.anthropic.com/v1/openai`                     | `chat/completions` | `choices[0].message.content` |
+| **Cohere**                     | `https://api.cohere.com/v2`                               | `chat`             | `message.content[0].text`    |
+| **Google Gemini**              | `https://generativelanguage.googleapis.com/v1beta/openai` | `chat/completions` | `choices[0].message.content` |
 
 > **Note**: Many providers offer OpenAI-compatible endpoints that work with the default settings.
+>
 > - Google Gemini: https://ai.google.dev/gemini-api/docs/openai
 > - Claude: https://docs.anthropic.com/en/api/openai-sdk
 
@@ -385,15 +411,18 @@ YAICLI works with all major LLM providers. The default configuration is set up f
 To configure a custom provider:
 
 1. **Find the API Endpoint**:
-   - Check the provider's API documentation for their chat completion endpoint
+
+    - Check the provider's API documentation for their chat completion endpoint
 
 2. **Identify the Response Structure**:
-   - Look at the JSON response format to find where the text content is located
+
+    - Look at the JSON response format to find where the text content is located
 
 3. **Set the Path Expression**:
-   - Use jmespath syntax to specify the path to the text content
+    - Use jmespath syntax to specify the path to the text content
 
 **Example**: For Claude's native API, the response looks like:
+
 ```json
 {
   "content": [
@@ -408,14 +437,14 @@ To configure a custom provider:
 }
 ```
 
-The path to extract the text is: `content.0.text`
+The path to extract the text is: `content.[0].text`
 
 ### Syntax Highlighting Themes
 
 YAICLI supports all Pygments syntax highlighting themes. You can set your preferred theme in the config file:
 
 ```ini
-CODE_THEME=monokai
+CODE_THEME = monokai
 ```
 
 Browse available themes at: https://pygments.org/styles/
@@ -449,13 +478,13 @@ ai --verbose "Explain quantum computing"
 Usage: ai [OPTIONS] [PROMPT]
 ```
 
-| Option | Short | Description |
-|--------|-------|-------------|
-| `--chat` | `-c` | Start in interactive chat mode |
-| `--shell` | `-s` | Generate and execute shell commands |
-| `--help` | `-h` | Show help message and exit |
-| `--verbose` | `-V` | Show detailed debug information |
-| `--template` | | Display the config template |
+| Option       | Short | Description                         |
+|--------------|-------|-------------------------------------|
+| `--chat`     | `-c`  | Start in interactive chat mode      |
+| `--shell`    | `-s`  | Generate and execute shell commands |
+| `--help`     | `-h`  | Show help message and exit          |
+| `--verbose`  | `-V`  | Show detailed debug information     |
+| `--template` |       | Display the config template         |
 
 ### Interactive Mode Features
 
@@ -464,12 +493,18 @@ Usage: ai [OPTIONS] [PROMPT]
 <td width="50%">
 
 **Commands**
-- `/exit` - Exit the application
+
 - `/clear` - Clear conversation history
 - `/his` - Show command history
+- `/list` - List saved chats
+- `/save <title>` - Save current chat with title
+- `/load <index>` - Load a saved chat
+- `/del <index>` - Delete a saved chat
+- `/exit` - Exit the application
 - `/mode chat|exec` - Switch modes
 
 **Keyboard Shortcuts**
+
 - `Tab` - Toggle between Chat/Execute modes
 - `Ctrl+C` or `Ctrl+D` - Exit
 - `Ctrl+R` - Search history
@@ -479,11 +514,13 @@ Usage: ai [OPTIONS] [PROMPT]
 <td width="50%">
 
 **Chat Mode** (💬)
+
 - Natural conversations with context
 - Markdown and code formatting
 - Reasoning display for complex queries
 
 **Execute Mode** (🚀)
+
 - Generate shell commands from descriptions
 - Review commands before execution
 - Edit commands before running
@@ -493,24 +530,112 @@ Usage: ai [OPTIONS] [PROMPT]
 </tr>
 </table>
 
+### Chat Persistent
+
+The `<PROMPT>` parameter in the chat mode will be used as a title to persist the chat content to the file system, with
+the save directory being a temporary directory, which may vary between machines, and it is determined on the first run.
+
+If the `<PROMPT>` parameter is not specified when entering `chat` mode, the session will be treated as a temporary
+session and will not be persisted. Of course, you can also manually call the `/save <title>` command to save during the
+chat.
+When you run the same `chat` command again, the previous session will be automatically loaded.
+
+```bash
+$ ai --chat "meaning of life"
+```
+
+> !NOTE: Chat mode is not supported when you redirect input to `ai` command.
+>
+> ```bash
+> $ cat error.log | ai --chat "Explain this error"
+> ```
+>
+> The above command will be parsed as `ai "cat error.log | ai "Explain this error"`.
+
+**Start a temporary chat session**
+
+```bash
+$ ai --chat
+```
+
+**Save a temporary chat session**
+
+```bash
+$ ai --chat
+Starting a temporary chat session (will not be saved automatically)
+...
+ 💬 > hi
+Assistant:
+Hello! How can I assist you today?
+───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+ 💬 > /save "hello"
+Chat saved as: hello
+Session is now marked as persistent and will be auto-saved on exit.
+───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+ 💬 >
+```
+
+**Start a persistent chat session**
+
+```bash
+$ ai --chat "check disk usage"
+```
+
+**Load a saved chat session**
+
+```bash
+$ ai --chat hello
+Chat title: hello
+
+ ██    ██  █████  ██  ██████ ██      ██
+  ██  ██  ██   ██ ██ ██      ██      ██
+   ████   ███████ ██ ██      ██      ██
+    ██    ██   ██ ██ ██      ██      ██
+    ██    ██   ██ ██  ██████ ███████ ██
+
+Welcome to YAICLI!
+Current: Persistent Session: hello
+Press TAB to switch mode
+/clear             : Clear chat history
+/his               : Show chat history
+/list              : List saved chats
+/save <title>      : Save current chat
+/load <index>      : Load a saved chat
+/del <index>       : Delete a saved chat
+/exit|Ctrl+D|Ctrl+C: Exit
+/mode chat|exec    : Switch mode (Case insensitive)
+───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+ 💬 > /his
+Chat History:
+1 User: hi
+    Assistant:
+    Hello! How can I assist you today?
+───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+ 💬 >
+```
+
 ### Input Methods
 
 **Direct Input**
+
 ```bash
 ai "What is the capital of France?"
 ```
 
 **Piped Input**
+
 ```bash
 echo "What is the capital of France?" | ai
 ```
 
 **File Analysis**
+
 ```bash
 cat demo.py | ai "Explain this code"
 ```
 
 **Combined Input**
+
 ```bash
 cat error.log | ai "Why am I getting these errors in my Python app?"
 ```
@@ -553,6 +678,7 @@ Output:
 
 ```bash
 $ ai --chat
+Starting a temporary chat session (will not be saved automatically)
 
  ██    ██  █████  ██  ██████ ██      ██
   ██  ██  ██   ██ ██ ██      ██      ██
@@ -561,12 +687,17 @@ $ ai --chat
     ██    ██   ██ ██  ██████ ███████ ██
 
 Welcome to YAICLI!
+Current: Temporary Session (use /save to make persistent)
 Press TAB to switch mode
 /clear             : Clear chat history
 /his               : Show chat history
+/list              : List saved chats
+/save <title>      : Save current chat
+/load <index>      : Load a saved chat
+/del <index>       : Delete a saved chat
 /exit|Ctrl+D|Ctrl+C: Exit
 /mode chat|exec    : Switch mode (Case insensitive)
-───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  💬 > Tell me about the solar system
 
 Assistant:
@@ -630,13 +761,13 @@ YAICLI is designed with a modular architecture that separates concerns and makes
 
 ### Dependencies
 
-| Library | Purpose |
-|---------|----------|
-| [Typer](https://typer.tiangolo.com/) | Command-line interface with type hints |
-| [Rich](https://rich.readthedocs.io/) | Terminal formatting and beautiful display |
+| Library                                                         | Purpose                                            |
+|-----------------------------------------------------------------|----------------------------------------------------|
+| [Typer](https://typer.tiangolo.com/)                            | Command-line interface with type hints             |
+| [Rich](https://rich.readthedocs.io/)                            | Terminal formatting and beautiful display          |
 | [prompt_toolkit](https://python-prompt-toolkit.readthedocs.io/) | Interactive input with history and auto-completion |
-| [httpx](https://www.python-httpx.org/) | Modern HTTP client with async support |
-| [jmespath](https://jmespath.org/) | JSON data extraction |
+| [httpx](https://www.python-httpx.org/)                          | Modern HTTP client with async support              |
+| [jmespath](https://jmespath.org/)                               | JSON data extraction                               |
 
 ## 👨‍💻 Contributing