asky-cli 0.1.6__py3-none-any.whl

asky/tools.py

@@ -0,0 +1,314 @@
+"""Tool execution functions for web search and URL content retrieval."""
+
+import json
+import os
+import requests
+import subprocess
+import time
+from datetime import datetime
+from typing import Any, Dict, List
+
+from asky.config import (
+    SEARXNG_URL,
+    MODELS,
+    SUMMARIZATION_MODEL,
+    SEARCH_PROVIDER,
+    SERPER_API_URL,
+    SERPER_API_KEY_ENV,
+    CUSTOM_TOOLS,
+    USER_AGENT,
+)
+from asky.html import HTMLStripper, strip_tags, strip_think_tags
+
+
+# Track URLs that have been read in the current session
+read_urls: List[str] = []
+
+
+def reset_read_urls() -> None:
+    """Reset the list of read URLs for a new session."""
+    global read_urls
+    read_urls = []
+
+
+def _execute_searxng_search(q: str, count: int) -> Dict[str, Any]:
+    """Execute a web search using SearXNG."""
+    # Ensure no trailing slash on SEARXNG_URL
+    base_url = SEARXNG_URL.rstrip("/")
+    try:
+        headers = {
+            "User-Agent": USER_AGENT,
+            "Accept": "application/json",
+        }
+        resp = requests.get(
+            f"{base_url}/search",
+            params={"q": q, "format": "json"},
+            headers=headers,
+            timeout=20,
+        )
+        if resp.status_code != 200:
+            return {"error": f"SearXNG error {resp.status_code}: {resp.text[:200]}"}
+
+        data = resp.json()
+        results = []
+        for x in data.get("results", [])[:count]:
+            results.append(
+                {
+                    "title": strip_tags(x.get("title", "")),
+                    "url": x.get("url"),
+                    "snippet": strip_tags(x.get("content", ""))[:400],
+                    "engine": x.get("engine"),
+                }
+            )
+        return {"results": results}
+    except Exception as e:
+        return {"error": f"SearXNG search failed: {str(e)}"}
+
+
+def _execute_serper_search(q: str, count: int) -> Dict[str, Any]:
+    """Execute a web search using Serper API."""
+    api_key = os.environ.get(SERPER_API_KEY_ENV)
+    if not api_key:
+        return {
+            "error": f"Serper API key not found in environment variable {SERPER_API_KEY_ENV}"
+        }
+
+    try:
+        headers = {
+            "X-API-KEY": api_key,
+            "Content-Type": "application/json",
+        }
+        payload = json.dumps({"q": q, "num": count})
+        resp = requests.post(
+            SERPER_API_URL,
+            headers=headers,
+            data=payload,
+            timeout=20,
+        )
+        resp.raise_for_status()
+        data = resp.json()
+        results = []
+        # Support both 'organic' and 'knowledgeGraph' if present
+        for x in data.get("organic", [])[:count]:
+            results.append(
+                {
+                    "title": strip_tags(x.get("title", "")),
+                    "url": x.get("link"),
+                    "snippet": strip_tags(x.get("snippet", ""))[:400],
+                    "engine": "serper",
+                }
+            )
+        return {"results": results}
+    except Exception as e:
+        return {"error": f"Serper search failed: {str(e)}"}
+
+
+def execute_web_search(args: Dict[str, Any]) -> Dict[str, Any]:
+    """Execute a web search using the configured provider."""
+    q = args.get("q", "")
+    count = args.get("count", 5)
+
+    if SEARCH_PROVIDER == "serper":
+        return _execute_serper_search(q, count)
+    else:
+        return _execute_searxng_search(q, count)
+
+
+def summarize_text(text: str) -> str:
+    """Summarize text using the defined summarization model."""
+    # Import here to avoid circular dependency
+    from asky.llm import get_llm_msg
+
+    if not text:
+        return ""
+
+    try:
+        messages = [
+            {
+                "role": "system",
+                "content": "You are a helpful assistant. Summarize the following text concisely, focusing on key facts.",
+            },
+            {
+                "role": "user",
+                "content": f"Text to summarize:\n\n{text[:50000]}",
+            },
+        ]
+
+        model_id = MODELS[SUMMARIZATION_MODEL]["id"]
+        msg = get_llm_msg(model_id, messages, tools=None)
+        return strip_think_tags(msg.get("content", ""))
+    except Exception as e:
+        return f"[Error in summarization: {str(e)}]"
+
+
+def _sanitize_url(url: str) -> str:
+    """Remove artifacts like shell-escaped backslashes from URLs."""
+    if not url:
+        return ""
+    # Remove backslashes which are often artifacts of shell-escaping parentheses or special chars
+    return url.replace("\\", "")
+
+
+def fetch_single_url(
+    url: str, max_chars: int, summarize: bool = False
+) -> Dict[str, str]:
+    """Fetch content from a single URL."""
+    url = _sanitize_url(url)
+    global read_urls
+    if url in read_urls:
+        return {url: "Error: Already read this URL."}
+    try:
+        headers = {"User-Agent": USER_AGENT}
+        resp = requests.get(url, headers=headers, timeout=20)
+        resp.raise_for_status()
+        content = strip_tags(resp.text)
+
+        if summarize:
+            content = f"Summary of {url}:\n" + summarize_text(content)
+        else:
+            content = content[:max_chars]
+
+        read_urls.append(url)
+        return {url: content}
+    except Exception as e:
+        return {url: f"Error: {str(e)}"}
+
+
+def execute_get_url_content(
+    args: Dict[str, Any], max_chars: int, summarize: bool
+) -> Dict[str, Any]:
+    """Fetch content from one or more URLs."""
+    header_url = args.get("url")
+    urls = args.get("urls", [])
+
+    # LLM can override the global summarize flag in its tool call
+    effective_summarize = args.get("summarize", summarize)
+
+    # Support both single 'url' and list 'urls'
+    if header_url:
+        urls.append(header_url)
+
+    # Deduplicate and filter empty
+    urls = list(set([u for u in urls if u]))
+
+    if not urls:
+        return {"error": "No URLs provided."}
+
+    results = {}
+    for i, url in enumerate(urls):
+        if i > 0 and effective_summarize:
+            # Small delay between summarizations to avoid hitting RPM limits
+            time.sleep(1)
+        results.update(fetch_single_url(url, max_chars, effective_summarize))
+
+    return results
+
+
+def execute_get_url_details(args: Dict[str, Any], max_chars: int) -> Dict[str, Any]:
+    """Fetch content and extract links from a URL."""
+    url = _sanitize_url(args.get("url", ""))
+    global read_urls
+    if url in read_urls:
+        return {"error": "You have already read this URL."}
+    try:
+        headers = {"User-Agent": USER_AGENT}
+        resp = requests.get(url, headers=headers, timeout=20)
+        resp.raise_for_status()
+        s = HTMLStripper()
+        s.feed(resp.text)
+
+        # Mark as read only after successful fetch
+        read_urls.append(url)
+
+        return {
+            "content": s.get_data()[:max_chars],
+            "links": s.get_links()[:50],  # Limit links to avoid context overflow
+            "system_note": "IMPORTANT: Do NOT use get_url_details again. Use get_url_content to read links.",
+        }
+    except Exception as e:
+        return {"error": f"Failed to fetch details: {str(e)}"}
+
+
+def execute_get_date_time() -> Dict[str, Any]:
+    """Return the current date and time."""
+    return {"date_time": datetime.now().isoformat()}
+
+
+def _execute_custom_tool(name: str, args: Dict[str, Any]) -> Dict[str, Any]:
+    """Execute a custom tool defined in config.toml."""
+    tool_cfg = CUSTOM_TOOLS.get(name)
+    if not tool_cfg:
+        return {"error": f"Custom tool configuration for '{name}' not found."}
+
+    cmd_base = tool_cfg.get("command", "")
+    if not cmd_base:
+        return {"error": f"No command defined for custom tool '{name}'."}
+
+    # Prepare arguments:
+    # 1. Get defaults from config
+    props = tool_cfg.get("parameters", {}).get("properties", {})
+    processed_args = {}
+
+    # 2. Merge defaults with provided args
+    # Note: LLM might already handle defaults, but we ensure it here
+    for k, p in props.items():
+        val = args.get(k)
+        if val is None:
+            val = p.get("default")
+
+        if val is not None:
+            # Remove existing double quotes and wrap in new ones
+            clean_val = str(val).replace('"', "")
+            processed_args[k] = f'"{clean_val}"'
+
+    try:
+        # Check if the command uses placeholders
+        if "{" in cmd_base and "}" in cmd_base:
+            try:
+                cmd_str = cmd_base.format(**processed_args)
+            except KeyError as e:
+                return {"error": f"Missing parameter required by command template: {e}"}
+        else:
+            # Append arguments in order of appearance in properties mapping
+            arg_list = []
+            for k in props.keys():
+                if k in processed_args:
+                    arg_list.append(processed_args[k])
+
+            cmd_str = f"{cmd_base} {' '.join(arg_list)}".strip()
+
+        print(f"Executing custom tool command: {cmd_str}")
+        result = subprocess.run(
+            cmd_str, shell=True, capture_output=True, text=True, timeout=30
+        )
+
+        return {
+            "stdout": result.stdout.strip(),
+            "stderr": result.stderr.strip(),
+            "exit_code": result.returncode,
+        }
+    except Exception as e:
+        return {"error": f"Failed to execute custom tool '{name}': {str(e)}"}
+
+
+def dispatch_tool_call(
+    call: Dict[str, Any], max_chars: int, summarize: bool
+) -> Dict[str, Any]:
+    """Dispatch a tool call to the appropriate executor."""
+    func = call["function"]
+    name = func["name"]
+    args = json.loads(func["arguments"]) if func.get("arguments") else {}
+    print(f"Dispatching tool call: {name} with args {args}")
+    if name == "web_search":
+        return execute_web_search(args)
+    if name == "get_url_content":
+        return execute_get_url_content(args, max_chars, summarize)
+    if name == "get_url_details":
+        return execute_get_url_details(args, max_chars)
+    if name == "get_date_time":
+        return execute_get_date_time()
+
+    if name in CUSTOM_TOOLS:
+        return _execute_custom_tool(name, args)
+
+    return {"error": f"Unknown tool: {name}"}

asky_cli-0.1.6.dist-info/METADATA

@@ -0,0 +1,290 @@
+Metadata-Version: 2.4
+Name: asky-cli
+Version: 0.1.6
+Summary: AI-powered web search CLI with LLM tool-calling capabilities
+License-Expression: MIT
+Requires-Python: >=3.10
+Requires-Dist: pyperclip>=1.11.0
+Requires-Dist: requests
+Requires-Dist: rich
+Description-Content-Type: text/markdown
+
+
+<img src="assets/asearch_icon.png" alt="asky icon" width="200" align="right">
+
+<font size="6">**asky**</font>
+
+
+AI-powered web search CLI with LLM tool-calling capabilities.
+
+asky (can be invoked as `asky` or `ask`) is a powerful command-line interface that brings AI-powered search and research capabilities directly to your terminal. It uses LLMs and tools to synthesize answers from the web (or from files and apps you have on your computer).
+## Key Features
+
+- **Multi-Model Support**: Easily define and switch between various LLMs and providers that supports OpenAI compatible API.
+- **Tool-Calling Integration**: Models can autonomously perform web searches (via SearXNG or Serper API), fetch URL content, and get current date/time to provide accurate, up-to-date answers.
+- **Intelligent Content Fetching**: Automatically strips HTML noise (scripts, styles) to provide clean text context to the models.
+- **Conversation History**: Maintains a local SQLite database of your queries and answers, allowing for context-aware follow-up questions.
+- **Deep Research Mode**: Automatically performs multiple searches to provide comprehensive analysis of complex topics.
+- **Deep Dive Mode**: Recursively explores links found on web pages for in-depth information gathering.
+- **Predefined Prompts**: Save and quickly invoke common prompt patterns using simple slashes (e.g., `/gn` for get latest news from The Guardian).
+- **Clipboard Integration**: Use `/cp` to expand the query with clipboard content.
+- **Custom Tools**: Expose any CLI command as a tool for the LLM. Define your own commands and parameters in `config.toml`.
+
+## How it Works
+
+1. **User Query**: You provide a query to the `ask` command.
+2. **Model Selection**: asky initializes the selected LLM based on your configuration.
+3. **Tool Loop**: The LLM analyzes your query. If it needs real-world data, it calls integrated tools (like `web_search`).
+4. **Context Synthesis**: asky fetches the data, cleans it, and feeds it back to the LLM. This process can repeat for up to 15 turns for complex research.
+5. **Final Answer**: The LLM synthesizes all gathered information into a concise, formatted response.
+6. **Persistence**: The interaction is saved to your local history for future reference.
+
+
+## Installation
+
+```bash
+pip install ask-cli
+```
+
+Or install from source:
+
+```bash
+pip install -e .
+```
+
+## Usage
+
+```
+
+# Basic query
+ask what is the weather in Berlin
+
+# Continue from previous query (by ID)
+ask -c 1 tell me more about that
+
+# Continue from last query (relative ID)
+ask -c~1 explain more
+# OR
+ask -c "~2" what about the one before that?
+
+> [!NOTE]
+> **Zsh Users**: When using `~` for relative IDs, you must either quote the value (e.g., `ask -c "~1"`) or place it immediately after the flag without a space (e.g., `ask -c~1`). If you use a space without quotes (e.g., `ask -c ~1`), zsh will attempt to expand it as a directory stack entry.
+
+
+➜  ~ ask -p
+
+=== USER PROMPTS ===
+  /gn         : Give me latest news from The Guardian, use https://www.theguardian.com/europe
+  /wh         : how is weather in
+====================
+
+➜  ~ ask /wh delft
+Dispatching tool call: web_search with args {'q': 'weather in Delft'}
+Dispatching tool call: get_url_content with args {'urls': ...}
+
+The weather in **Delft, South Holland, Netherlands** is currently **45°F and Cloudy with Showers in the Vicinity** (as of 4:20 pm CET).
+
+Here is the forecast for today and the next couple of days:
+
+...
+
+Query completed in 3.88 seconds
+
+--------------------------------------------------------------------------------
+➜  ~ ask --help
+usage: ask [-h] [-m {gf,glmair,glmflash,q34t,q34,lfm,q8,q30,onano,omini}] [-d [DEEP_RESEARCH]] [-dd] [-c CONTINUE_IDS] [-s] [-fs] [--cleanup-db [CLEANUP_DB]] [--all]
+           [-H [HISTORY]] [-pa PRINT_IDS] [-p] [-v]
+           [query ...]
+
+Tool-calling CLI with model selection.
+
+positional arguments:
+  query                 The query string
+
+options:
+  -h, --help            show this help message and exit
+  -m, --model {gf,glmair,glmflash,q34t,q34,lfm,q8,q30,onano,omini}
+                        Select the model alias
+  -d, --deep-research [DEEP_RESEARCH]
+                        Enable deep research mode (optional: specify min number of queries, default 5)
+  -dd, --deep-dive      Enable deep dive mode (extracts links and encourages reading more pages from same domain)
+  -c, --continue-chat CONTINUE_IDS
+                        Continue conversation with context from specific history IDs (comma-separated, e.g. '1,2').
+  -s, --summarize       Enable summarize mode (summarizes URL content and uses summaries for chat context)
+  -fs, --force-search   Force the model to use web search (default: False).
+                        Helpful for avoiding hallucinations with small models
+  --cleanup-db [CLEANUP_DB]
+                        Delete history records. usage: --cleanup-db [ID|ID-ID|ID,ID] or --cleanup-db --all
+  --all                 Used with --cleanup-db to delete ALL history.
+  -H, --history [HISTORY]
+                        Show last N queries and answer summaries (default 10).
+                        Use with --print-answer to print the full answer(s).
+  -pa, --print-answer PRINT_IDS
+                        Print the answer(s) for specific history IDs (comma-separated).
+  -p, --prompts         List all configured user prompts.
+  -v, --verbose         Enable verbose output (prints config and LLM inputs).
+```
+
+**Deep research mode** (encourages model to perform multiple searches)
+
+ask -d 5 comprehensive analysis of topic
+
+**Deep dive mode** (encourages model to read multiple pages from same domain)
+
+ask -dd https://example.com
+
+**Use a specific model**
+
+ask -m gf what is quantum computing
+
+**Force web search**
+
+ask -fs latest news on topic
+
+
+**Pre-configured model definitions**
+
+Followin model definitions ship with default config.toml, but you can add any number of models that are served with an OpenAI compatible API.
+
+- `gf` - Google Gemini Flash (default)
+- `lfm` - Liquid LFM 2.5
+- `q8` - Qwen3 8B
+- `q30` - Qwen3 30B
+- `q34` - Qwen3 4B
+- `q34t` - Qwen3 4B Thinking
+
+## Custom Tools
+
+You can define your own tools in `config.toml` that the LLM can use to interact with your local system. Each tool runs a CLI command and returns the output to the LLM.
+
+Example configuration for a `list_dir` tool:
+
+```toml
+[tool.list_dir]
+command = "ls"
+description = "List the contents of a directory."
+
+[tool.list_dir.parameters]
+type = "object"
+required = ["path"]
+
+[tool.list_dir.parameters.properties.path]
+type = "string"
+default = "."
+```
+
+Example configuration for a `grep_search` tool:
+
+```toml
+[tool.grep_search]
+command = "grep -r {pattern} {path}"
+description = "Search for a pattern in files recursively."
+
+[tool.grep_search.parameters]
+type = "object"
+required = ["pattern"]
+
+[tool.grep_search.parameters.properties.pattern]
+type = "string"
+description = "The regex pattern to search for."
+
+[tool.grep_search.parameters.properties.path]
+type = "string"
+description = "The directory path to search in."
+default = "."
+```
+
+> [!CAUTION]
+> **Security Risk**: Custom tools execute commands using your system shell. While asky attempts to quote arguments safely, exposing powerful CLI tools to an LLM can be risky. Use this feature with caution.
+
+### How it works:
+- **Placeholders**: Use `{param_name}` in the `command` string to inject arguments. If no placeholders are found, arguments are appended to the command.
+- **Quoting**: All arguments are automatically cleaned (inner double-quotes removed) and wrapped in double-quotes for safety.
+- **Execution**: Commands are executed via terminal shell, allowing for advanced piping and redirection.
+
+> [!TIP]
+> **Performance Tip**: When using recursive tools like `grep`, consider excluding large directories like `.venv` or `node_modules` to avoid timeouts:
+> `command = "grep -r --exclude-dir={.venv,node_modules} {pattern} {path}"`
+
+> [!NOTE]
+> **Optional Parameters**: If you define a parameter with a `default` value in `config.toml`, it will be automatically injected into your `command` if the LLM omits it.
+
+## Configuration options
+[See default configuration](./src/asky/config.toml)
+
+
+On first run, a default configuration file is created at `~/.config/asky/config.toml`. You can edit this file to configure models, API keys, and other settings.
+
+### API Keys
+You can set API keys in two ways:
+1. **Environment Variables**: Set `GOOGLE_API_KEY` (or other configured env vars) in your shell.
+2. **Config File**: Add keys directly to `[api.name]` sections in `config.toml`.
+
+Example `config.toml`:
+```toml
+[general]
+default_model = "gf"
+
+[api.gemini]
+api_key_env = "GOOGLE_API_KEY"
+
+[api.lmstudio]
+url = "http://localhost:1234/v1/chat/completions"
+```
+
+### Verification
+Run with `-v` to see the loaded configuration:
+```bash
+ask -v
+```
+
+
+## Web Search
+
+asky works best with a web search tool. You can use SearXNG or Serper API. 
+
+### Serper API
+Serper is a paid service, but gives 2500 requests for free. 
+
+### Install & configure SearXNG
+SearXNG is free and open source, it's easy to set up with a single docker command.
+
+Following command taken from [SearXNG docs](https://docs.searxng.org/admin/installation-docker.html#instancing).
+```bash
+docker pull docker.io/searxng/searxng:latest
+
+# Create directories for configuration and persistent data
+$ mkdir -p ./searxng/config/ ./searxng/data/
+$ cd ./searxng/
+
+# Run the container
+$ docker run --name searxng -d \
+    -p 8888:8080 \
+    -v "./config/:/etc/searxng/" \
+    -v "./data/:/var/cache/searxng/" \
+    docker.io/searxng/searxng:latest
+```
+You need to add "-json" to the formats section of the default searxng config.yaml file.
+```yaml
+  # remove format to deny access, use lower case.
+  # formats: [html, csv, json, rss]
+  formats:
+    - html
+    - json
+```
+Then restart the container.
+```bash
+docker restart searxng
+```
+
+
+
+## Requirements
+
+- Python 3.10+
+- Running SearXNG instance or Serper API key.
+- LM Studio (for local models) or API keys for remote models
+
+## License
+
+MIT

asky_cli-0.1.6.dist-info/RECORD

@@ -0,0 +1,14 @@
+asky/__init__.py,sha256=7VmWT0rB9Bxx9OkRdd0-J934J9DMwO8h7jKwva8OuGI,160
+asky/__main__.py,sha256=QlI65PwFjeU7adUyTzMMaX6ArDVPuvqjY1DViZb3-k4,106
+asky/banner.py,sha256=ucEVPj840J2wvECM8CaBRa6CqvEjMGotY1HLiyeIjqA,3655
+asky/cli.py,sha256=txY4JfTECPG7fYbfkYOdeNDxYik0iYaIV2YNX9uBEGc,16620
+asky/config.py,sha256=Ti7V5MZAneP48qqTj2K_RRSw6kNKIdB_J--XBLjmqig,9100
+asky/config.toml,sha256=yvfM5IhH3qPMnVhxpy0Ak4IZ1l8Ic5crhoX_yuV4-X0,7827
+asky/html.py,sha256=ZJJsLQlUFpPO8OYrhHV3o_G2mmEdF2SU0sUVs6-8k2I,1805
+asky/llm.py,sha256=VKAmsGO_AQvLIuXuLE8NztBFKR4PtvK9OrR1yhTzRew,12758
+asky/storage.py,sha256=91PkV6gnZkjayEGIgFHN7zeYCxqMOuquuPGq4aFKv4E,4944
+asky/tools.py,sha256=_myR4ntshgJH6oRhDumxdrXkF-8j5Ry79Rt_obyNP_c,10034
+asky_cli-0.1.6.dist-info/METADATA,sha256=pGPI9UKCDJ3r9t44sahuowPnLDFQSAPI7qr5_9Z-PAc,10321
+asky_cli-0.1.6.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+asky_cli-0.1.6.dist-info/entry_points.txt,sha256=_Q-svN8lIJemHnlPjGmZPBi6cfWd9nuK6NGNLDT8c8w,59
+asky_cli-0.1.6.dist-info/RECORD,,

asky_cli-0.1.6.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

asky_cli-0.1.6.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+ask = asky.cli:main
+asky = asky.cli:main