agent-cli 0.70.5__py3-none-any.whl → 0.72.1__py3-none-any.whl

agent_cli/_extras.json

@@ -2,8 +2,8 @@
   "wyoming": ["Wyoming protocol for ASR/TTS servers", ["wyoming"]],
   "audio": ["Local audio recording/playback", ["numpy", "sounddevice", "wyoming"]],
   "llm": ["LLM framework (pydantic-ai)", ["pydantic_ai"]],
-  "memory": ["Long-term memory proxy", ["chromadb", "yaml"]],
-  "rag": ["RAG proxy (ChromaDB, embeddings)", ["chromadb"]],
+  "memory": ["Long-term memory proxy", ["chromadb", "openai", "yaml"]],
+  "rag": ["RAG proxy (ChromaDB, embeddings)", ["chromadb", "openai"]],
   "server": ["FastAPI server components", ["fastapi"]],
   "speed": ["Audio speed adjustment (audiostretchy)", ["audiostretchy"]],
   "piper": ["Local Piper TTS", ["piper"]],

agent_cli/_requirements/memory.txt

@@ -7,6 +7,7 @@ annotated-types==0.7.0
 anyio==4.12.1
     # via
     #   httpx
+    #   openai
     #   starlette
     #   watchfiles
 attrs==25.4.0
@@ -45,7 +46,9 @@ colorama==0.4.6 ; os_name == 'nt' or sys_platform == 'win32'
 coloredlogs==15.0.1
     # via onnxruntime
 distro==1.9.0
-    # via posthog
+    # via
+    #   openai
+    #   posthog
 dnspython==2.8.0
     # via email-validator
 dotenv==0.9.9
@@ -96,6 +99,7 @@ httpx==0.28.1
     #   chromadb
     #   fastapi
     #   fastapi-cloud-cli
+    #   openai
 huggingface-hub==0.36.0
     # via
     #   agent-cli
@@ -115,6 +119,8 @@ importlib-resources==6.5.2
     # via chromadb
 jinja2==3.1.6
     # via fastapi
+jiter==0.12.0
+    # via openai
 jsonschema==4.26.0
     # via chromadb
 jsonschema-specifications==2025.9.1
@@ -142,6 +148,8 @@ onnxruntime==1.20.1
     # via
     #   agent-cli
     #   chromadb
+openai==2.15.0
+    # via agent-cli
 opentelemetry-api==1.39.1
     # via
     #   chromadb
@@ -195,6 +203,7 @@ pydantic==2.12.5
     #   chromadb
     #   fastapi
     #   fastapi-cloud-cli
+    #   openai
     #   pydantic-extra-types
     #   pydantic-settings
 pydantic-core==2.41.5
@@ -281,6 +290,8 @@ six==1.17.0
     #   kubernetes
     #   posthog
     #   python-dateutil
+sniffio==1.3.1
+    # via openai
 starlette==0.50.0
     # via fastapi
 sympy==1.14.0
@@ -295,6 +306,7 @@ tqdm==4.67.1
     # via
     #   chromadb
     #   huggingface-hub
+    #   openai
     #   transformers
 transformers==4.57.5
     # via agent-cli
@@ -313,6 +325,7 @@ typing-extensions==4.15.0
     #   fastapi
     #   grpcio
     #   huggingface-hub
+    #   openai
     #   opentelemetry-api
     #   opentelemetry-exporter-otlp-proto-grpc
     #   opentelemetry-sdk

agent_cli/_requirements/rag.txt

@@ -7,6 +7,7 @@ annotated-types==0.7.0
 anyio==4.12.1
     # via
     #   httpx
+    #   openai
     #   starlette
     #   watchfiles
 attrs==25.4.0
@@ -61,7 +62,9 @@ cryptography==46.0.3
 defusedxml==0.7.1
     # via markitdown
 distro==1.9.0
-    # via posthog
+    # via
+    #   openai
+    #   posthog
 dnspython==2.8.0
     # via email-validator
 dotenv==0.9.9
@@ -112,6 +115,7 @@ httpx==0.28.1
     #   chromadb
     #   fastapi
     #   fastapi-cloud-cli
+    #   openai
 huggingface-hub==0.36.0
     # via
     #   agent-cli
@@ -131,6 +135,8 @@ importlib-resources==6.5.2
     # via chromadb
 jinja2==3.1.6
     # via fastapi
+jiter==0.12.0
+    # via openai
 jsonschema==4.26.0
     # via chromadb
 jsonschema-specifications==2025.9.1
@@ -173,6 +179,8 @@ onnxruntime==1.20.1
     #   chromadb
     #   magika
     #   markitdown
+openai==2.15.0
+    # via agent-cli
 opentelemetry-api==1.39.1
     # via
     #   chromadb
@@ -232,6 +240,7 @@ pydantic==2.12.5
     #   chromadb
     #   fastapi
     #   fastapi-cloud-cli
+    #   openai
     #   pydantic-extra-types
     #   pydantic-settings
 pydantic-core==2.41.5
@@ -322,6 +331,8 @@ six==1.17.0
     #   markdownify
     #   posthog
     #   python-dateutil
+sniffio==1.3.1
+    # via openai
 soupsieve==2.8.1
     # via beautifulsoup4
 starlette==0.50.0
@@ -338,6 +349,7 @@ tqdm==4.67.1
     # via
     #   chromadb
     #   huggingface-hub
+    #   openai
     #   transformers
 transformers==4.57.5
     # via agent-cli
@@ -357,6 +369,7 @@ typing-extensions==4.15.0
     #   fastapi
     #   grpcio
     #   huggingface-hub
+    #   openai
     #   opentelemetry-api
     #   opentelemetry-exporter-otlp-proto-grpc
     #   opentelemetry-sdk

agent_cli/_requirements/vad.txt

@@ -14,89 +14,22 @@ click==8.3.1
     #   typer-slim
 colorama==0.4.6 ; sys_platform == 'win32'
     # via click
-coloredlogs==15.0.1
-    # via onnxruntime
 dotenv==0.9.9
     # via agent-cli
-filelock==3.20.3
-    # via torch
-flatbuffers==25.12.19
-    # via onnxruntime
-fsspec==2026.1.0
-    # via torch
 h11==0.16.0
     # via httpcore
 httpcore==1.0.9
     # via httpx
 httpx==0.28.1
     # via agent-cli
-humanfriendly==10.0
-    # via coloredlogs
 idna==3.11
     # via
     #   anyio
     #   httpx
-jinja2==3.1.6
-    # via torch
 markdown-it-py==4.0.0
     # via rich
-markupsafe==3.0.3
-    # via jinja2
 mdurl==0.1.2
     # via markdown-it-py
-mpmath==1.3.0
-    # via sympy
-networkx==3.6.1
-    # via torch
-numpy==2.3.5
-    # via onnxruntime
-nvidia-cublas-cu12==12.8.4.1 ; platform_machine == 'x86_64' and sys_platform == 'linux'
-    # via
-    #   nvidia-cudnn-cu12
-    #   nvidia-cusolver-cu12
-    #   torch
-nvidia-cuda-cupti-cu12==12.8.90 ; platform_machine == 'x86_64' and sys_platform == 'linux'
-    # via torch
-nvidia-cuda-nvrtc-cu12==12.8.93 ; platform_machine == 'x86_64' and sys_platform == 'linux'
-    # via torch
-nvidia-cuda-runtime-cu12==12.8.90 ; platform_machine == 'x86_64' and sys_platform == 'linux'
-    # via torch
-nvidia-cudnn-cu12==9.10.2.21 ; platform_machine == 'x86_64' and sys_platform == 'linux'
-    # via torch
-nvidia-cufft-cu12==11.3.3.83 ; platform_machine == 'x86_64' and sys_platform == 'linux'
-    # via torch
-nvidia-cufile-cu12==1.13.1.3 ; platform_machine == 'x86_64' and sys_platform == 'linux'
-    # via torch
-nvidia-curand-cu12==10.3.9.90 ; platform_machine == 'x86_64' and sys_platform == 'linux'
-    # via torch
-nvidia-cusolver-cu12==11.7.3.90 ; platform_machine == 'x86_64' and sys_platform == 'linux'
-    # via torch
-nvidia-cusparse-cu12==12.5.8.93 ; platform_machine == 'x86_64' and sys_platform == 'linux'
-    # via
-    #   nvidia-cusolver-cu12
-    #   torch
-nvidia-cusparselt-cu12==0.7.1 ; platform_machine == 'x86_64' and sys_platform == 'linux'
-    # via torch
-nvidia-nccl-cu12==2.27.5 ; platform_machine == 'x86_64' and sys_platform == 'linux'
-    # via torch
-nvidia-nvjitlink-cu12==12.8.93 ; platform_machine == 'x86_64' and sys_platform == 'linux'
-    # via
-    #   nvidia-cufft-cu12
-    #   nvidia-cusolver-cu12
-    #   nvidia-cusparse-cu12
-    #   torch
-nvidia-nvshmem-cu12==3.3.20 ; platform_machine == 'x86_64' and sys_platform == 'linux'
-    # via torch
-nvidia-nvtx-cu12==12.8.90 ; platform_machine == 'x86_64' and sys_platform == 'linux'
-    # via torch
-onnxruntime==1.20.1
-    # via silero-vad
-packaging==25.0
-    # via
-    #   onnxruntime
-    #   silero-vad
-protobuf==6.33.4
-    # via onnxruntime
 psutil==7.2.1 ; sys_platform == 'win32'
     # via agent-cli
 pydantic==2.12.5
@@ -107,8 +40,6 @@ pygments==2.19.2
     # via rich
 pyperclip==1.11.0
     # via agent-cli
-pyreadline3==3.5.4 ; sys_platform == 'win32'
-    # via humanfriendly
 python-dotenv==1.2.1
     # via dotenv
 rich==14.2.0
@@ -118,26 +49,12 @@ rich==14.2.0
     #   typer-slim
 setproctitle==1.3.7
     # via agent-cli
-setuptools==80.9.0 ; python_full_version >= '3.12'
-    # via torch
 shellingham==1.5.4
     # via
     #   typer
     #   typer-slim
-silero-vad==6.2.0
+silero-vad-lite==0.2.1
     # via agent-cli
-sympy==1.14.0
-    # via
-    #   onnxruntime
-    #   torch
-torch==2.9.1
-    # via
-    #   silero-vad
-    #   torchaudio
-torchaudio==2.9.1
-    # via silero-vad
-triton==3.5.1 ; platform_machine == 'x86_64' and sys_platform == 'linux'
-    # via torch
 typer==0.21.1
     # via agent-cli
 typer-slim==0.21.1
@@ -147,7 +64,6 @@ typing-extensions==4.15.0
     #   anyio
     #   pydantic
     #   pydantic-core
-    #   torch
     #   typer
     #   typer-slim
     #   typing-inspection

agent_cli/agents/assistant.py

@@ -1,29 +1,4 @@
-r"""Wake word-based voice assistant that records when wake word is detected.
-
-This agent uses Wyoming wake word detection to implement a hands-free voice assistant that:
-1. Continuously listens for a wake word
-2. When the wake word is detected, starts recording user speech
-3. When the wake word is detected again, stops recording and processes the speech
-4. Sends the recorded speech to ASR for transcription
-5. Optionally processes the transcript with an LLM and speaks the response
-
-WORKFLOW:
-1. Agent starts listening for the specified wake word
-2. First wake word detection -> start recording user speech
-3. Second wake word detection -> stop recording and process the speech
-4. Transcribe the recorded speech using Wyoming ASR
-5. Optionally process with LLM and respond with TTS
-
-USAGE:
-- Start the agent: assistant --wake-word "ok_nabu" --input-device-index 1
-- The agent runs continuously until stopped with Ctrl+C or --stop
-- Uses background process management for daemon-like operation
-
-REQUIREMENTS:
-- Wyoming wake word server (e.g., wyoming-openwakeword)
-- Wyoming ASR server (e.g., wyoming-whisper)
-- Optional: Wyoming TTS server for responses
-"""
+"""Wake word-based voice assistant using Wyoming protocol services."""
 
 from __future__ import annotations
 
@@ -313,7 +288,28 @@ def assistant(
     config_file: str | None = opts.CONFIG_FILE,
     print_args: bool = opts.PRINT_ARGS,
 ) -> None:
-    """Wake word-based voice assistant using local or remote services."""
+    """Hands-free voice assistant using wake word detection.
+
+    Continuously listens for a wake word, then records your speech until you say
+    the wake word again. The recording is transcribed and sent to an LLM for a
+    conversational response, optionally spoken back via TTS.
+
+    **Conversation flow:**
+      1. Say wake word → starts recording
+      2. Speak your question/command
+      3. Say wake word again → stops recording and processes
+
+    The assistant runs in a loop, ready for the next command after each response.
+    Stop with Ctrl+C or `--stop`.
+
+    **Requirements:**
+      - Wyoming wake word server (e.g., wyoming-openwakeword on port 10400)
+      - Wyoming ASR server (e.g., wyoming-whisper on port 10300)
+      - Optional: TTS server for spoken responses (enable with `--tts`)
+
+    **Example:**
+      `assistant --wake-word ok_nabu --tts --input-device-name USB`
+    """
     if print_args:
         print_command_line_args(locals())
 

agent_cli/agents/autocorrect.py

@@ -1,4 +1,4 @@
-"""Read text from clipboard, correct it using a local or remote LLM, and write the result back to the clipboard."""
+"""Fix grammar, spelling, and punctuation in text using an LLM."""
 
 from __future__ import annotations
 
@@ -216,7 +216,7 @@ def autocorrect(
     *,
     text: str | None = typer.Argument(
         None,
-        help="The text to correct. If not provided, reads from clipboard.",
+        help="Text to correct. If omitted, reads from system clipboard.",
         rich_help_panel="General Options",
     ),
     # --- Provider Selection ---
@@ -240,7 +240,33 @@ def autocorrect(
     config_file: str | None = opts.CONFIG_FILE,
     print_args: bool = opts.PRINT_ARGS,
 ) -> None:
-    """Correct text from clipboard using a local or remote LLM."""
+    """Fix grammar, spelling, and punctuation using an LLM.
+
+    Reads text from clipboard (or argument), sends to LLM for correction,
+    and copies the result back to clipboard. Only makes technical corrections
+    without changing meaning or tone.
+
+    **Workflow:**
+    1. Read text from clipboard (or `TEXT` argument)
+    2. Send to LLM for grammar/spelling/punctuation fixes
+    3. Copy corrected text to clipboard (unless `--json`)
+    4. Display result
+
+    **Examples:**
+    ```bash
+    # Correct text from clipboard (default)
+    agent-cli autocorrect
+
+    # Correct specific text
+    agent-cli autocorrect "this is incorect"
+
+    # Use OpenAI instead of local Ollama
+    agent-cli autocorrect --llm-provider openai
+
+    # Get JSON output for scripting (disables clipboard)
+    agent-cli autocorrect --json
+    ```
+    """
     if print_args:
         print_command_line_args(locals())
 

agent_cli/agents/chat.py

@@ -1,13 +1,15 @@
-"""An chat agent that you can talk to.
-
-This agent will:
-- Listen for your voice command.
-- Transcribe the command.
-- Send the transcription to an LLM.
-- Speak the LLM's response.
-- Remember the conversation history.
-- Attach timestamps to the saved conversation.
-- Format timestamps as "ago" when sending to the LLM.
+"""Voice-based conversational chat agent with memory and tools.
+
+Runs an interactive voice loop: listens for speech, transcribes it,
+sends to the LLM (with conversation context), and optionally speaks the response.
+
+**Available tools** (automatically used by the LLM when relevant):
+- `add_memory`/`search_memory`/`update_memory` - persistent long-term memory
+- `duckduckgo_search` - web search for current information
+- `read_file`/`execute_code` - file access and shell commands
+
+**Process management**: Use `--toggle` to start/stop via hotkey, `--stop` to terminate,
+or `--status` to check if running. Useful for binding to a keyboard shortcut.
 """
 
 from __future__ import annotations
@@ -425,14 +427,15 @@ def chat(
     history_dir: Path = typer.Option(  # noqa: B008
         "~/.config/agent-cli/history",
         "--history-dir",
-        help="Directory to store conversation history.",
+        help="Directory for conversation history and long-term memory. "
+        "Both `conversation.json` and `long_term_memory.json` are stored here.",
         rich_help_panel="History Options",
     ),
     last_n_messages: int = typer.Option(
         50,
         "--last-n-messages",
-        help="Number of messages to include in the conversation history."
-        " Set to 0 to disable history.",
+        help="Number of past messages to include as context for the LLM. "
+        "Set to 0 to start fresh each session (memory tools still persist).",
         rich_help_panel="History Options",
     ),
     # --- General Options ---
@@ -444,7 +447,34 @@ def chat(
     config_file: str | None = opts.CONFIG_FILE,
     print_args: bool = opts.PRINT_ARGS,
 ) -> None:
-    """An chat agent that you can talk to."""
+    """Voice-based conversational chat agent with memory and tools.
+
+    Runs an interactive loop: listen → transcribe → LLM → speak response.
+    Conversation history is persisted and included as context for continuity.
+
+    **Built-in tools** (LLM uses automatically when relevant):
+
+    - `add_memory`/`search_memory`/`update_memory` - persistent long-term memory
+    - `duckduckgo_search` - web search for current information
+    - `read_file`/`execute_code` - file access and shell commands
+
+    **Process management**: Use `--toggle` to start/stop via hotkey (bind to
+    a keyboard shortcut), `--stop` to terminate, or `--status` to check state.
+
+    **Examples**:
+
+    Use OpenAI-compatible providers for speech and LLM, with TTS enabled:
+
+        agent-cli chat --asr-provider openai --llm-provider openai --tts
+
+    Start in background mode (toggle on/off with hotkey):
+
+        agent-cli chat --toggle
+
+    Use local Ollama LLM with Wyoming ASR:
+
+        agent-cli chat --llm-provider ollama
+    """
     if print_args:
         print_command_line_args(locals())
 

agent_cli/agents/memory/__init__.py

@@ -9,7 +9,25 @@ from agent_cli.core.process import set_process_title
 
 memory_app = typer.Typer(
     name="memory",
-    help="Memory system operations (add, proxy, etc.).",
+    help="""Long-term memory system for AI chat applications.
+
+Provides persistent memory across conversations by storing facts and context
+in Markdown files, with automatic vector indexing for semantic retrieval.
+
+**Subcommands:**
+
+- `proxy`: Start an OpenAI-compatible proxy that injects relevant memories
+  into chat requests and extracts new facts from responses
+- `add`: Manually add facts/memories without going through LLM extraction
+
+**Quick Start:**
+
+    # Start the memory proxy (point your chat client at localhost:8100)
+    agent-cli memory proxy --openai-base-url http://localhost:11434/v1
+
+    # Manually seed some memories
+    agent-cli memory add "User prefers dark mode" "User is a Python developer"
+""",
     add_completion=True,
     rich_markup_mode="markdown",
     no_args_is_help=True,

agent_cli/agents/memory/add.py

@@ -127,17 +127,17 @@ def add(
         "default",
         "--conversation-id",
         "-c",
-        help="Conversation ID to add memories to.",
+        help="Conversation namespace for these memories. Memories are retrieved per-conversation unless shared globally.",
     ),
     memory_path: Path = typer.Option(  # noqa: B008
         "./memory_db",
         "--memory-path",
-        help="Path to the memory store.",
+        help="Directory for memory storage (same as `memory proxy --memory-path`).",
     ),
     git_versioning: bool = typer.Option(
         True,  # noqa: FBT003
         "--git-versioning/--no-git-versioning",
-        help="Commit changes to git.",
+        help="Auto-commit changes to git for version history.",
     ),
     quiet: bool = opts.QUIET,
     config_file: str | None = opts.CONFIG_FILE,

agent_cli/agents/memory/proxy.py

@@ -19,7 +19,7 @@ from agent_cli.core.utils import console, print_command_line_args
 def proxy(
     memory_path: Path = typer.Option(  # noqa: B008
         "./memory_db",
-        help="Path to the memory store (files + derived vector index).",
+        help="Directory for memory storage. Contains `entries/` (Markdown files) and `chroma/` (vector index). Created automatically if it doesn't exist.",
         rich_help_panel="Memory Configuration",
     ),
     openai_base_url: str | None = opts.OPENAI_BASE_URL,
@@ -27,7 +27,7 @@ def proxy(
     openai_api_key: str | None = opts.OPENAI_API_KEY,
     default_top_k: int = typer.Option(
         5,
-        help="Number of memory entries to retrieve per query.",
+        help="Number of relevant memories to inject into each request. Higher values provide more context but increase token usage.",
         rich_help_panel="Memory Configuration",
     ),
     host: str = opts.SERVER_HOST,
@@ -38,7 +38,7 @@ def proxy(
     ),
     max_entries: int = typer.Option(
         500,
-        help="Maximum stored memory entries per conversation (excluding summary).",
+        help="Maximum entries per conversation before oldest are evicted. Summaries are preserved separately.",
         rich_help_panel="Memory Configuration",
     ),
     mmr_lambda: float = typer.Option(
@@ -48,7 +48,7 @@ def proxy(
     ),
     recency_weight: float = typer.Option(
         0.2,
-        help="Recency score weight (0.0-1.0). Controls freshness vs. relevance. Default 0.2 (20% recency, 80% semantic relevance).",
+        help="Weight for recency vs semantic relevance (0.0-1.0). At 0.2: 20% recency, 80% semantic similarity.",
         rich_help_panel="Memory Configuration",
     ),
     score_threshold: float = typer.Option(
@@ -59,16 +59,16 @@ def proxy(
     summarization: bool = typer.Option(
         True,  # noqa: FBT003
         "--summarization/--no-summarization",
-        help="Enable automatic fact extraction and summaries.",
+        help="Extract facts and generate summaries after each turn using the LLM. Disable to only store raw conversation turns.",
         rich_help_panel="Memory Configuration",
     ),
     git_versioning: bool = typer.Option(
         True,  # noqa: FBT003
         "--git-versioning/--no-git-versioning",
-        help="Enable automatic git commit of memory changes.",
+        help="Auto-commit memory changes to git. Initializes a repo in `--memory-path` if needed. Provides full history of memory evolution.",
         rich_help_panel="Memory Configuration",
     ),
-    log_level: opts.LogLevel = opts.LOG_LEVEL,
+    log_level: opts.LogLevel = opts.SERVER_LOG_LEVEL,
     config_file: str | None = opts.CONFIG_FILE,
     print_args: bool = opts.PRINT_ARGS,
 ) -> None:
@@ -78,7 +78,7 @@ def proxy(
     CLI, or IDE plugin) and an OpenAI-compatible LLM provider (e.g., OpenAI,
     Ollama, vLLM).
 
-    Key Features:
+    **Key Features:**
 
     - **Simple Markdown Files:** Memories are stored as human-readable Markdown
       files, serving as the ultimate source of truth.
@@ -89,7 +89,7 @@ def proxy(
     - **Proxy Middleware:** Works transparently with any OpenAI-compatible
       `/chat/completions` endpoint.
 
-    How it works:
+    **How it works:**
 
     1.  Intercepts `POST /v1/chat/completions` requests.
     2.  **Retrieves** relevant memories (facts, previous conversations) from a
@@ -99,8 +99,17 @@ def proxy(
     5.  **Extracts** new facts from the conversation in the background and
         updates the long-term memory store (including handling contradictions).
 
-    Use this to give "long-term memory" to any OpenAI-compatible application.
-    Point your client's base URL to `http://localhost:8100/v1`.
+    **Example:**
+
+        # Start proxy pointing to local Ollama
+        agent-cli memory proxy --openai-base-url http://localhost:11434/v1
+
+        # Then configure your chat client to use http://localhost:8100/v1
+        # as its OpenAI base URL. All requests flow through the memory proxy.
+
+    **Per-request overrides:** Clients can include these fields in the request
+    body: `memory_id` (conversation ID), `memory_top_k`, `memory_recency_weight`,
+    `memory_score_threshold`.
     """
     if print_args:
         print_command_line_args(locals())