{"id":23946075,"url":"https://github.com/acrion/ditana-assistant","last_synced_at":"2025-04-12T18:30:51.659Z","repository":{"id":271025085,"uuid":"910595149","full_name":"acrion/ditana-assistant","owner":"acrion","description":"Ditana Assistant: AI-powered CLI/GUI tool for intelligent assistance, leveraging LLMs with OS interaction capabilities and context augmentation, optionally via Wolfram|Alpha","archived":false,"fork":false,"pushed_at":"2025-03-17T08:51:25.000Z","size":854,"stargazers_count":10,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-03-26T12:47:09.222Z","etag":null,"topics":["ai-assistant","cli-tool","context-augmentation","ditana","gui-application-python","huggingface-datasets","koboldcpp","linux","llms","macos","openai-api","os-interaction","windows","wolfram-alpha-api"],"latest_commit_sha":null,"homepage":"https://ditana.org/assistant","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/acrion.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"acrion","liberapay":"acrion","buy_me_a_coffee":"acrion","patreon":"acriondev"}},"created_at":"2024-12-31T18:44:55.000Z","updated_at":"2025-03-18T20:41:52.000Z","dependencies_parsed_at":"2025-03-17T10:45:59.803Z","dependency_job_id":null,"html_url":"https://github.com/acrion/ditana-assistant","commit_stats":null,"previous_names":["acrion/ditana-assistant"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acrion%2Fditana-assistant","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acrion%2Fditana-assistant/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acrion%2Fditana-assistant/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acrion%2Fditana-assistant/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/acrion","download_url":"https://codeload.github.com/acrion/ditana-assistant/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248613208,"owners_count":21133463,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-assistant","cli-tool","context-augmentation","ditana","gui-application-python","huggingface-datasets","koboldcpp","linux","llms","macos","openai-api","os-interaction","windows","wolfram-alpha-api"],"created_at":"2025-01-06T08:21:50.000Z","updated_at":"2025-04-12T18:30:51.639Z","avatar_url":"https://github.com/acrion.png","language":"Python","funding_links":["https://github.com/sponsors/acrion","https://liberapay.com/acrion","https://buymeacoffee.com/acrion","https://patreon.com/acriondev"],"categories":["Python"],"sub_categories":[],"readme":"# Ditana Assistant\n\nDitana Assistant is an innovative AI-powered application that combines a graphical user interface with terminal functionality and, optionally, Introspective Contextual Augmentation via Wolfram|Alpha. Even without Wolfram|Alpha, the Introspective Contextual Augmentation (ICA) enhances AI responses in many cases (see [Example Sessions](#example-sessions) for more details).\n\nIt leverages Large Language Models (LLMs) to provide intelligent assistance similar to the native browser interfaces of AI service providers.\n\nThe name stems from its integration into the Arch-based Linux distribution [Ditana GNU/Linux](https://ditana.org), but it runs on other Linux distributions, macOS, and Windows (including PowerShell support).\n\nSimply ask your question in natural language, for example\n\n- _What are the largest files in the current directory and below?_\n- _Is the network name resolution service running stably?_\n- _Which process is consuming so much CPU time?_\n- _Replace all occurrences of the word 'sun' with 'moon' in the file ./project/test_\n- _What’s my current audio device?_\n\nFor complete sessions, see [Examples](#example-sessions).\n\n## Key Features\n\n- **AI Integration**: Uses a [KoboldCpp](https://github.com/LostRuins/koboldcpp/wiki) server with the [Google Gemma model](https://ai.google.dev/gemma/docs/base).\n- **Flexible Configuration**: Can be configured to use OpenAI models through a simple YAML [configuration file](#configuration).\n- **OS Interaction**: Capable of interacting with the operating system, suggesting and executing terminal commands upon user confirmation, see [example sessions](#terminal-command-generation-examples).\n- **Optional Wolfram|Alpha Integration**: Automatically attempts to augment the LLM’s context via communication with the official [Wolfram|Alpha Short Answers API](https://products.wolframalpha.com/short-answers-api/explorer).\n- **Introspective Contextual Augmentation (ICA)**: Enhances AI responses by automatically gathering and incorporating relevant contextual information through introspective reasoning.\nSee [Introspective Contextual Augmentation](#introspective-contextual-augmentation-ica) for more details.\n- **Multi-Platform**: Runs on Linux, macOS, and Windows, adapting to each environment automatically by [collecting context of the running system](#assistance-based-on-your-specific-system).\n- **Dual-Mode Operation**: Functions both as a [GUI application](#gui-mode) and a stand-alone [terminal tool](#command-line-interface) for quick command generation and embedding of answers in scripts.\n- **Pastime Mode**: Engage in [human-like conversations](#pastime-mode) with an AI companion, optionally impersonating specific characters or personalities.\n- **Intelligent Caching**: Implements a [sophisticated request caching system](#intelligent-caching) for both Wolfram|Alpha and LLM queries, optimizing API usage and response times.\n\n## Table of Contents\n\n\u003c!-- toc --\u003e\n\n- [Usage](#usage)\n  * [Command-line Interface](#command-line-interface)\n  * [GUI Mode](#gui-mode)\n  * [Pastime Mode](#pastime-mode)\n  * [Intelligent Caching](#intelligent-caching)\n- [Installation](#installation)\n  * [Ditana GNU/Linux](#ditana-linux)\n  * [Arch Linux and Arch-based Distributions](#arch-linux-and-arch-based-distributions)\n  * [Other Linux Distributions, Windows, and macOS](#other-linux-distributions-windows-and-macos)\n  * [Prerequisites](#prerequisites)\n- [Configuration](#configuration)\n  * [Available Configuration Options:](#available-configuration-options)\n  * [Configuration Option Details](#configuration-option-details)\n  * [Using OpenAI](#using-openai)\n  * [Using Wolfram|Alpha](#using-wolframalpha)\n- [Use Cases](#use-cases)\n  * [Maximizing the Underlying AI Model’s Potential](#maximizing-the-underlying-ai-models-potential)\n  * [Terminal Command Generation](#terminal-command-generation)\n  * [Assistance Based on Your Specific System](#assistance-based-on-your-specific-system)\n  * [All Use Cases of Wolfram|Alpha](#all-use-cases-of-wolframalpha)\n  * [Introspective Contextual Augmentation (ICA)](#introspective-contextual-augmentation-ica)\n- [Example Sessions](#example-sessions)\n  * [Terminal command generation examples](#terminal-command-generation-examples)\n  * [Introspective Contextual Augmentation (ICA) examples](#introspective-contextual-augmentation-ica-examples)\n- [Collaboration](#collaboration)\n- [Sponsorship](#sponsorship)\n- [Current Project Status](#current-project-status)\n  * [Platform Support](#platform-support)\n  * [Ongoing and Future Development](#ongoing-and-future-development)\n- [Important Notes](#important-notes)\n- [Licensing](#licensing)\n- [Author](#author)\n\n\u003c!-- tocstop --\u003e\n\n## Usage\n\n### Command-line Interface\n\n```bash\nditana-assistant [OPTIONS] [TASK]\n```\n\nOptions:\n- `-h`, `--help`: Show help message and exit.\n- `-v`, `--version`: Show the version of Ditana Assistant and exit.\n- `-u`, `--gui`: Display a graphical dialog.\n- `-a`, `--augmentation`: Enable [Introspective Contextual Augmentation (ICA)](#introspective-contextual-augmentation-ica) for enhanced AI responses.\n- `-w`, `--wolfram-alpha`: Force use of [Wolfram|Alpha](#all-use-cases-of-wolframalpha) for first prompt.\n- `-q`, `--quiet`: Run in quiet mode. No progress output, no continuation of dialog (except confirmation of command execution).\n- `-p`, `--pastime`: Activate Pastime mode for engaging in human-like conversations.\n- `-i IMPERSONATE`, `--impersonate IMPERSONATE`: In Pastime mode, optionally impersonate a specified person or character.\n\nDitana Assistant supports specifying arbitrary tasks via command line arguments, which are then used as the initial prompt.\nThis feature allows for versatile usage, from simple calculations to complex queries.\n\nFor instance, you can use Ditana Assistant as a sophisticated calculator:\n\n```bash\n❯ ./ditana-assistant --quiet \"solve x^2 + 2x + 5 = 0\"\nthe 1st is x equals minus 1 minus 2 times i and the 2nd is x equals minus 1 plus 2 times i\n```\n\nThis example demonstrates a direct output from Wolfram|Alpha’s Short Answers API, used for immediately suitable queries.\nTherefore, the language style of the output can be more formal than the natural style of LLMs.\nHowever, in the majority of cases, Ditana Assistant employs Wolfram|Alpha internally for [Introspective Contextual Augmentation](#key-features),\nenabling a powerful synergy between Wolfram|Alpha and the LLM to generate more comprehensive responses.\n\nThe complexity of the responses scales with the nature of your query.\nFor more intricate tasks, Ditana Assistant can provide detailed, comprehensive answers.\nPlease refer to the [Example Sessions](#example-sessions) section for demonstrations of more advanced use cases.\n\nNote: The `--quiet` flag is used in this example to display only the assistant’s response without additional output.\n\n### GUI Mode\n\nTo start Ditana Assistant in GUI mode:\n\n```bash\nditana-assistant -u\n```\n\n\u003cimg src=\"ditana-assistant-gui.png\" alt=\"Ditana Assistant GUI\" width=\"60%\" height=\"60%\"\u003e\n\nThis screenshot illustrates the seamless integration of real-time data from the Wolfram|Alpha API, which is automatically accessed as needed. The assistant leverages this capability to provide up-to-date and context-aware responses.\n\nFor a more comprehensive understanding of the assistant’s capabilities, please refer to the [Use Cases](#maximizing-the-underlying-ai-models-potential) and [Example Sessions](#example-sessions).\n\n### Pastime Mode\n\nPastime mode allows users to engage in human-like conversations with the AI assistant.\nThis feature is particularly effective when using more advanced language models like gpt-4o-mini (see section [Configuration](#configuration))\n\nTo activate Pastime mode:\n\n```bash\nditana-assistant -p\n```\n\nTo impersonate a specific character or personality:\n\n```\nditana-assistant -p -i \"Detective Sherlock Holmes\"\nAh, good afternoon. So you're the one who asked me for help.\nPlease tell me everything you know about the incident.\n\nYour Message (‘enter’ to quit): All I know is that there was a lot of fog.\nI could hardly see anything. And suddenly the car was gone. Just disappeared. It was terrible.\n\nInteresting. Can you tell me more about the car? Make, colour, registration number?\n\nYour Message (‘enter’ to quit): It was a green VW Beetle. Licence plate number MN P-16.\n\nThank you for the information. Did you see any suspects or people behaving suspiciously?\n\nYour Message (‘enter’ to quit): Precisely not, because of the fog. I only remember that,\nstrangely enough, a parrot flew past just before the incident. That's very strange,\nbecause parrots are not native to this area.\n\nA parrot, you say? That is indeed unusual. Have you noticed anything else that you think\nis important?\n```\n\nThe above conversation was done using `gpt-3.5-turbo`. Another example, using `gpt-4` (without `-i`):\n\n\u003cimg src=\"pastime-sample.png\" alt=\"Pastime Mode\" width=\"40%\" height=\"40%\"\u003e\n\nNote: While Pastime mode is functional with the Gemma model, it performs best with more advanced models like gpt-4o-mini. The conversations with Gemma may be less engaging and limited in scope.\n\n### Intelligent Caching\n\nDitana Assistant implements a sophisticated request caching system for both Wolfram|Alpha and LLM queries. This feature optimizes API usage and improves response times, especially for repeated or similar queries.\n\nKey aspects of the caching system:\n- Caches all outgoing requests to APIs.\n- Implements an intelligent lifetime management for cache entries.\n- Adapts cache lifetime based on the stability of responses.\n- Initial cache lifetime depends on API: 1 week for LLMs, ≈ 11 minutes for Wolfram|Alpha.\n- Particularly beneficial for internal queries made by Ditana Assistant, which often lack dialog history.\n- Maximum cache size can be [configured](#advanced-configuration).\n\nThis caching mechanism significantly reduces API calls, especially for short, repetitive queries, leading to improved performance and reduced API usage.\n\n## Installation\n\n### Ditana GNU/Linux\n\nDitana Assistant is integrated into the Ditana GNU/Linux distribution with native Arch packages. For more information, visit [https://ditana.org](https://ditana.org).\n\nThe corresponding package in the Ditana Arch repository is `ditana-assistant`. Note that this package does not depend on the [ditana-koboldcpp AUR package](https://aur.archlinux.org/packages/ditana-koboldcpp), because you have free choice of which AI API you want to use, including OpenAI.\n`ditana-koboldcpp` includes an optimized configuration for the Gemma language model.\nIn KoboldCpp operation mode, the assistant makes use of [Gemma’s prompt format](https://ai.google.dev/gemma/docs/formatting).\n\n### Other Linux Distributions, Windows, and macOS\n\nFor other platforms, including Windows and macOS, you can install Ditana Assistant from source using [Poetry](https://python-poetry.org):\n\n1. Clone the repository:\n   ```bash\n   git clone https://github.com/acrion/ditana-assistant.git\n   cd ditana-assistant\n   ```\n\n2. Install Poetry:\n   ```bash\n   pip install poetry\n   ```\n   \n3. Install ditana-assistant’s dependencies:\n   ```bash\n   poetry install\n   ```\n   This command will create a virtual environment (if one does not already exist) and install all dependencies listed in the `pyproject.toml` file.\n   To execute ditana-assistant, you need to spawn a shell within the virtual environment with this command:\n\n   ```bash\n   poetry shell\n   ```\n   \n   The dependencies include either an [OpenAI API key](https://platform.openai.com/account/api-keys) or a local [KoboldCpp server](https://github.com/LostRuins/koboldcpp/wiki).\n   For the latter, please consider using Google’s [Gemma LLM](https://ai.google.dev/gemma) ([Download](https://huggingface.co/bartowski/gemma-2-2b-it-GGUF/resolve/main/gemma-2-2b-it-Q6_K.gguf)),\n   as Ditana Assistant utilizes [Gemma’s Instruct Tag Format](https://ai.google.dev/gemma/docs/formatting).\n   For this, you should select the Instruct Tag Preset `Gemma 2` in KoboldCpp’s Format settings.\n\n#### Why no requirements.txt?\n\nDitana Assistant uses **Poetry** to manage dependencies, which eliminates the need for a `requirements.txt` file.\nPoetry provides a `pyproject.toml` file to define dependencies and a `poetry.lock` file to lock the exact versions of these dependencies for consistency across different environments.\nThis approach simplifies dependency management by ensuring that all environments use the exact same versions, reducing potential conflicts.\n\nFor more information on how Poetry manages dependencies, visit the [Poetry documentation](https://python-poetry.org/docs/).\n\n### Prerequisites\n\nDitana Assistant supports two main operating modes:\n\n1. **Local operation with KoboldCpp:**\n   - A running [KoboldCpp server](https://github.com/LostRuins/koboldcpp/wiki) is required.\n   - In KoboldCpp operation mode, the Ditana Assistant makes use of [Gemma’s prompt format](https://ai.google.dev/gemma/docs/formatting).\n   - You can download the recommended model here: [gemma-2-2b-it-GGUF](https://huggingface.co/bartowski/gemma-2-2b-it-GGUF).\n   - Arch Linux users can get everything required by installing the [ditana-koboldcpp AUR package](https://aur.archlinux.org/packages/ditana-koboldcpp).\n\n2. **Cloud-based operation with OpenAI API:**\n   - Alternatively, you can use the OpenAI API without any local model setup.\n   - This requires [configuration](#configuration) and an [OpenAI API key](https://platform.openai.com/account/api-keys).\n\nChoose the mode that best fits your needs and system capabilities.\n\n## Configuration\n\nThe Ditana Assistant configuration is stored in a YAML file located at:\n\n- Linux: `~/.config/ditana-assistant/config.yaml`\n- macOS: `~/Library/Application Support/ditana-assistant/config.yaml`\n- Windows: `C:\\Users\\\u003cusername\u003e\\AppData\\Local\\ditana-assistant\\config.yaml`\n\n### Available Configuration Options:\n\n```yaml\nassume_english: false\nenable_experimental_features: false\ngenerate_terminal_cmd: true\nkoboldcpp_base_url: http://localhost:5001  # when using Gemma\nmodel_cache_size: 20\nmodel_cache_start_lifetime_sec: 604800\nmodel_type: gemma # or 'openai'\noffer_cmd_execution: true\nopenai_model: gpt-4o-mini  # when using OpenAI\nshow_debug_messages: false\nwolfram_alpha_cache_size: 1\nwolfram_alpha_cache_start_lifetime_sec: 675\nwolfram_alpha_error_cache_size: 1\nwolfram_alpha_error_cache_start_lifetime_sec: 604800\nwolfram_alpha_short_answers_app_id: '' # https://developer.wolframalpha.com\n```\n\n### Configuration Option Details\n\n#### Core Functionality Settings\n\n- `model_type`: Specifies the AI model to use. Currently, `gemma` for KoboldCpp and `openai` for OpenAI models are supported. Also see [Using OpenAI](#using-openai).\nDefault: `gemma` (requires local [KoboldCpp server](#prerequisites))\n\n- `koboldcpp_base_url`: The base URL of the KoboldCpp server, used when `model_type` is set to `gemma`. Default: `http://localhost:5001`\n\n- `openai_model`: The specific OpenAI model to use when model_type is set to openai, see [Using OpenAI](#using-openai). Default: `gpt-4o-mini`\n\n- `wolfram_alpha_short_answers_app_id`: The App ID for Wolfram|Alpha’s Short Answers API, see [Using Wolfram|Alpha](#using-wolframalpha). Default: `''`'\n\n- `generate_terminal_cmd`: If enabled, the wizard will analyse the user’s input to see if it relates to their computer and can be solved by a terminal command. The terminal command is only offered for execution if `offer_cmd_execution` is also enabled. Default: `true`.\n\n- `offer_cmd_execution`: If enabled, the assistant will offer to execute detected terminal commands based on the output. This usually happens together with `generate_terminal_cmd`, but not necessarily. Default: `true`.\n\n#### Advanced Configuration\n\n- `assume_english`: If set to true, the assistant will assume all text is in English without performing language detection. \nLanguage detection is only used for specific use cases such as Wolfram|Alpha or internal meta-requests that need to be combined with the user prompt. Default: `false`.\n\n- `enable_experimental_features`: Activates experimental features for development and testing purposes. This is intended for internal use to systematically test new functionalities. Use with caution as features are still in development. Default: `false`.\n\n- `model_cache_size`: Maximum size (in MiB) of the cache used for model responses. Note that the actual cache file size will be approximately 1/3 larger due to JSON formatting overhead. Default: `20` MiB.\n\n- `model_cache_start_lifetime_sec`: The initial lifetime (in seconds) for model cache entries. When this period expires, the cache entry is re-evaluated; if a new response matches the cached one, the lifetime is extended, otherwise, it is shortened. Default: `604800` seconds (1 week).\n\n- `show_debug_messages`: Controls whether debug messages are displayed during the assistant’s operation. Useful for troubleshooting. Default: `false`.\n\n- `wolfram_alpha_cache_size`: Maximum size (in MiB) of the cache used for storing responses from the Wolfram|Alpha API. The actual file size will be approximately 1/3 larger due to JSON syntax. Default: `1` MiB.\n\n- `wolfram_alpha_cache_start_lifetime_sec`: The initial lifetime (in seconds) for Wolfram|Alpha cache entries. The lifetime is adjusted based on whether subsequent API responses remain consistent or change. Default: `675` seconds.\n\n- `wolfram_alpha_error_cache_size`: Maximum size (in MiB) of the cache used for failed Wolfram|Alpha API requests. This helps avoid repeated requests for errors. Default: `1` MiB.\n\n- `wolfram_alpha_error_cache_start_lifetime_sec`: The initial lifetime (in seconds) for entries in the error cache. Lifetimes are adjusted based on whether the error persists. Default: `604800` seconds (1 week).\n\n### Using OpenAI\n\nSet the `OPENAI_API_KEY` environment variable with your [OpenAI API key](https://platform.openai.com/account/api-keys) when configuring OpenAI models (see below config entries `model_type` and `openai_model`).\nAs of October 2024, gpt-4o-mini is a factor of 20 cheaper than gpt-3.5-turbo: [$0.150 / 1M input tokens](https://openai.com/api/pricing).\nAccording to [https://platform.openai.com/docs/models/gpt-3-5-turbo](https://platform.openai.com/docs/models/gpt-3-5-turbo):\n  \u003e \"As of July 2024, gpt-4o-mini should be used in place of gpt-3.5-turbo, as it is cheaper, more capable, multimodal, and just as fast. gpt-3.5-turbo is still available for use in the API.\"\n\nNote that the number of API accesses is reduced by Ditana Assistant’s sophisticated [caching algorithm](#intelligent-caching).\n\n### Using Wolfram|Alpha\n\nObtain an App ID by creating a \"Short Answers API Key\" on https://developer.wolframalpha.com and set the config entry `wolfram_alpha_short_answers_app_id` to its value.\nMake sure to select `Short Answers API` in the dialog:  \n\u003cimg src=\"wolfram_alpha_short_answers_api_key.png\" alt=\"Wolfram Alpha Short Answers API Key\" width=\"50%\" height=\"50%\"\u003e  \n  \nCurrently, 2000 accesses per month [are free](https://products.wolframalpha.com/api).\nNote that the number of API accesses is reduced by Ditana Assistant’s sophisticated [caching algorithm](#intelligent-caching).\n\n## Use Cases\n\n### Maximizing the Underlying AI Model’s Potential\n\nDitana Assistant is designed to maximize the potential of its underlying AI model, offering capabilities that surpass typical browser-based interactions:\n\n1. **[Integration of Multiple Knowledge Sources](#ica-example-1-using-gpt-35-turbo-and-wolframalpha)**: By combining the AI model’s capabilities with Wolfram|Alpha’s factual database (when enabled), Ditana Assistant offers a broader range of assistance, from creative problem-solving to precise calculations and up-to-date information.\n\n2. **[Introspective Contextual Augmentation (ICA)](#introspective-contextual-augmentation-ica)**: By introspectively augmenting the context of queries, Ditana Assistant provides more accurate and relevant responses. This feature improves AI answers in many cases, even when used without Wolfram|Alpha.\n\n3. **[System-Specific Context](#assistance-based-on-your-specific-system)**: The assistant automatically adds information about your specific system environment, allowing for more precise and tailored responses. This context includes details about your operating system, shell type, and running applications.\n\n### Terminal Command Generation\n\n- Generating complex terminal commands\n- Process and performance monitoring\n- File and system management\n- Audio device configuration\n- Text manipulation in files\n- System log analysis\n\nSee [Example Section](#terminal-command-generation-examples) for demonstration.\n\n### Assistance Based on Your Specific System\n\nCurrently, the following information is collected from your system to tailor the LLM’s answers to your needs:\n\n- The type of shell you started the Assistant from (important for terminal commands)\n- The desktop type\n- Running desktop applications\n- Your date, time and time zone\n- Your preferred language (based on your temporal locale identifier, platform-independent)\n- In Terminal Mode, the current directory\n\n### All Use Cases of Wolfram|Alpha\n\n- Real-time information like statistics such as population, weather and much more (see [sample session](#ica-example-1-using-gpt-35-turbo-and-wolframalpha))\n- Mathematics (see [sample session](#command-line-interface))\n- [Factual, highly accurate knowledge](https://www.wolframalpha.com/knowledgebase) without the occasional inconsistencies or inaccuracies that may occur with LLMs\n\n### Introspective Contextual Augmentation (ICA)\n\nIntrospective Contextual Augmentation is a powerful feature of Ditana Assistant that [significantly](#statistical-evaluation-and-optimization) enhances the quality and accuracy of AI responses. This innovative approach creates a synergy between various knowledge sources, including the AI model’s own introspective capabilities and Wolfram|Alpha (when enabled).\n\n**Note: This feature is turned off by default.** Users can enable it through the UI or by using the `-a` command line switch when using the terminal tool.\n\n#### Key Aspects of ICA\n\n1. **Dynamic Information Gathering**:\n   - The assistant automatically generates and processes contextual queries to supplement user inputs.\n   - Adapts to each specific request, creating a more tailored response.\n\n2. **Dual-Source Augmentation**:\n   - With Wolfram|Alpha: Incorporates up-to-date information such as current weather, statistics, and more.\n   - Without Wolfram|Alpha: Engages in self-dialogue, using the underlying LLM to answer contextual queries, enhancing response quality through introspection.\n\n3. **Adaptive Contextual Queries**:\n   - Dynamically generates relevant questions based on the user’s input.\n   - These questions are answered either by Wolfram|Alpha or the LLM itself, creating a form of \"inner monologue\".\n\n4. **Guided Introspective Reasoning**:\n   - Incorporates contextual queries and their answers into the message history before addressing the main user prompt.\n   - Guides the LLM through a structured, introspective approach to problem-solving.\n   - Allows the model to break down complex problems and approach them more systematically, even when engaging in self-dialogue.\n   - The main user prompt is kept unchanged, but with additional context due to the messages automatically inserted into the dialogue.\n\n5. **Enhanced Problem-Solving**:\n   - Leverages additional context and guided introspective reasoning.\n   - Provides more comprehensive and accurate solutions to complex problems.\n\n6. **Improved Accuracy**:\n   - Reduces errors and inconsistencies in AI responses.\n   - Provides additional relevant information and a structured thought process before addressing the main query.\n\n7. **LLM Capability Maximization**:\n   - Even without external sources like Wolfram|Alpha, helps the LLM leverage its own knowledge more effectively.\n   - Utilizes a guided, multi-step introspective reasoning approach.\n\n#### Example of ICA in Action\n\nTo illustrate how ICA works, here’s an example from the [MMLU multitask test](https://huggingface.co/datasets/cais/mmlu) (without using Wolfram|Alpha):\n\n```\nQuestion: A victim and a defendant both worked as longshoremen at a shipyard. After the victim\nwas shot to death, the defendant was tried for murder and acquitted. Following the acquittal,\nthe victim's estate sued the defendant in a wrongful death action. During the civil trial, the\nvictim's estate called a witness to testify. The witness, who worked with both men at the\nshipyard, testified that two weeks before the shooting, the victim came to work with a broken\nnose and said that the defendant had caused it. The attorney for the victim's estate then\nasked the witness the following question, \"Was the defendant present during your conversation\nwith the victim, and if so, did he say anything about the victim's broken nose?\" The witness\nreplied, \"Yes, the defendant was present, and after the victim told me that the defendant\nbroke his nose, the defendant said, And that's only the beginning.\" Upon objection by the\ndefendant's attorney, the witness's testimony is\n\nChoices:\nB. admissible, because it reports a declaration against interest.\nC. admissible, because it reports the defendant's adoptive admission of the victim's assertion.\nD. inadmissible, because of the principle of collateral estoppel.\nE. inadmissible, because it is hearsay not within any recognized exception.\n\nCorrect answer: C\n\nModel’s answer (without ICA feature): E\n\n                            systematic contextual query: \"What legal principle governs the admissibility of the witness's testimony regarding the defendant...\"\n                             answer to systematic query: \"In the scenario, a victim and a defendant, both longshoremen at a shipyard, were involved in a ca...\"\n   Are you sure? Please answer only with \"yes\" or \"no\".: \"no.\"\n                                      critical question: \"What specific hearsay exception could potentially apply to the defendant's statement, and how mig...\"\n                            answer to critical question: \"The specific hearsay exception that could potentially apply to the defendant's statement is the \"...\"\nModel’s answer (with ICA feature): C\n```\n\nThis example demonstrates how ICA guides the model through a series of contextual queries, helping it arrive at the correct answer.\n\nPlease note that the additional questions and answers you see in the above log merely reflect a subset of the internal processes, and in particular,\ndo not provide the context in which they occur. Furthermore, the generation of the questions is not logged. The objective of this log is to provide an overview\nof the internal processes. While additional log outputs [can be enabled](#advanced-configuration), they clutter the output.\n\n#### Technical Implementation\n\n1. **Query Generation**:\n   - Utilizes meta-questions to the LLM to generate contextual queries.\n   - Employs meta-meta-questions to generate the questions themselves.\n   - Developed through extensive trial and error to determine effective query strategies.\n\n2. **Dialogue Structure**:\n   - Creates independent dialogues separate from the main conversation.\n   - The main dialogue is then constructed based on the context derived from these sub-dialogues.\n\n3. **Prompt Engineering**:\n   - Varies the prompt structure based on the current step in the procedure.\n   - Converts LLM-generated questions (initially Assistant messages) into User messages for efficient processing.\n   - Sometimes repeats dialogues within a single message instead of using separate messages, depending on efficiency requirements.\n\n4. **Experimental Features**:\n   - Explored recursive calls with limitations to ensure prompts become progressively shorter.\n   - Implemented in the `generate_sub_prompts` function in the `text_processors_ai` module.\n   - [Socratic method](https://en.wikipedia.org/wiki/Socratic_method) simulation (`socratic_method` function) attempted but not yet yielding statistically significant improvements.\n\n#### Statistical Evaluation and Optimization\n\n1. **Benchmark Tests**:\n   - Utilized the [MMLU multitask test](https://huggingface.co/datasets/cais/mmlu) (14,042 questions) and the [ARC-Challenge test](https://huggingface.co/datasets/allenai/ai2_arc) (1,172 questions).\n   - Optimization primarily conducted using the ARC-Challenge test.\n\n2. **Performance Improvements**:\n   - MMLU test: Corrected 188 (5.6%) of 3,348 initially incorrect answers using the OpenAI model `gpt-4o-mini`.\n   - ARC-Challenge test: Fixed 26 out of 94 initially incorrect answers.\n\n3. **Statistical Significance**:\n   - Employed [McNemar’s statistical test](https://en.wikipedia.org/wiki/McNemar's_test) to verify improvements.\n   - Achieved over 99% probability of significant differences in all cases.\n   - Despite optimization on ARC-Challenge potentially affecting statistical significance, MMLU results confirmed the effectiveness.\n\n4. **Methodology**:\n   - Conducted tests without Wolfram|Alpha to evaluate the ICA process capability independently.\n   - Ran the ARC-Challenge test multiple times (4) due to potential variations in LLM API responses.\n\n5. **Documentation and Transparency**:\n   - Complete test logs available for download [here](https://ditana.org/assistant/ica-benchmark-409f40f.log).\n   - Logged subset of internal processes to provide an overview without cluttering output.\n\n#### Evaluation Methodology for Multiple-Choice Questions\n\nThe evaluation of Large Language Models (LLMs) on multiple-choice questions presents unique challenges, particularly when using pre-existing datasets. This section outlines the methodology employed in this project, discussing its rationale and comparing it to other potential approaches.\n\n##### Dataset Preparation and Prompt Engineering\n\nIt’s crucial to note that many multiple-choice datasets, including those from HuggingFace like [ai2_arc](https://huggingface.co/datasets/allenai/ai2_arc) and [cais_mmlu](https://huggingface.co/datasets/cais/mmlu),\nprovide only the question text and a list of answer choices.\nThey do not include a pre-formatted prompt suitable for direct input to an LLM. Consequently, researchers must design an appropriate prompt structure.\n\nIn this project, the `process_question` function was developed to transform raw dataset entries into suitable prompts. This function constructs a prompt that clearly delineates the question and answer choices, concluding with an explicit instruction for the model to provide the letter of the correct answer.\n\n##### Challenges with Standard Evaluation Metrics\n\nInitial attempts at evaluation utilized the HuggingFace [evaluate](https://github.com/huggingface/evaluate) library, specifically the [bertscore](https://huggingface.co/spaces/evaluate-metric/bertscore) and Google Research [rouge](https://huggingface.co/spaces/evaluate-metric/rouge) metrics.\nThese metrics are widely used for various natural language processing tasks.\nHowever, manual verification of individual question evaluations revealed significant discrepancies in accurately identifying correct and incorrect responses in the multiple-choice context.\n\n##### Development of a Specialized Evaluation Method\n\nIn response to these challenges, a specialized method for evaluating multiple-choice responses was developed.\nThis method capitalizes on the structured nature of multiple-choice answers and the linguistic properties of English.\nKey aspects of this approach include:\n\n1. **Answer Choice Labeling**: The method ensures that answer choices begin with \"B\" rather than \"A\".\nThis is crucial because \"A\" frequently appears as an article in English text, whereas \"B\", \"C\", \"D\", etc., are less likely to appear as standalone words.\n\n2. **Response Parsing**: The LLM’s response is analyzed for the presence of valid answer choice labels (e.g., \"B\", \"C\", \"D\") as whole words.\nThis approach significantly reduces false positives compared to more complex semantic analysis methods.\n\n3. **Validation Criteria**:\n   - A response is considered valid if exactly one answer choice label is present.\n   - If multiple valid labels are detected, the response is deemed incorrect.\n   - If no valid label is found, the response is also considered incorrect.\n   - The response is correct only if the detected label matches the dataset’s provided answer.\n\nThis method has shown high reliability in manual verification, outperforming the initially tested [bertscore](https://huggingface.co/spaces/evaluate-metric/bertscore) and Google Research [rouge](https://huggingface.co/spaces/evaluate-metric/rouge) metrics for this specific task.\n\n##### Considerations and Future Work\n\nWhile this specialized method has proven effective, it’s important to acknowledge that the HuggingFace [evaluate](https://github.com/huggingface/evaluate) library may contain other evaluation methods specifically designed for multiple-choice questions that were not explored in this project.\nFuture work could involve a comprehensive comparison of this method against other potential evaluation techniques for multiple-choice responses.\n\nMoreover, the necessity of prompt engineering in working with these datasets highlights an important consideration in LLM evaluation: the impact of prompt design on model performance.\nThis aspect warrants further investigation and standardization efforts in the field of LLM evaluation.\n\n#### Experimentation and Further Development\n\n1. **Modular Design**:\n   - Modifications can be implemented under the condition `Configuration.get()['ENABLE_EXPERIMENTAL_FEATURES']`.\n   - Allows for easy testing and benchmarking of new features.\n\n2. **Benchmarking Process**:\n   - Use the `-e` option when running benchmarks to evaluate experimental modifications.\n   - Statistical significance is calculated continuously after each question using [McNemar's statistical test](https://en.wikipedia.org/wiki/McNemar's_test), allowing for early detection of significant improvements or deteriorations.\n   - Typically requires 2,000-3,000 questions to achieve robust statistical significance.\n   - This approach quickly determines if changes are beneficial or detrimental, enabling efficient iteration and refinement of experimental features.\n\n3. **Ongoing Development of Experimental Features**:\n   - Building upon the experimental features mentioned in the [Technical Implementation](#technical-implementation) section, several areas are being actively explored and refined:\n     - Further development of recursive techniques with result summarization, expanding on the `generate_sub_prompts` function.\n     - Continued optimization of the [Socratic method](https://en.wikipedia.org/wiki/Socratic_method) simulation, aiming to achieve statistically significant improvements.\n     - Enhancement of query generation and dialogue construction methods to improve context understanding and response relevance.\n   - These developments aim to push the boundaries of the ICA feature’s capabilities while maintaining efficient API usage and overall performance.\n\n4. **Open for Contributions**:\n   - The Python codebase allows for easy integration of new ideas and techniques.\n   - Encourages experimentation within the `augment_context_introspectively` method in the `conversation_manager` module.\n\nBy leveraging these techniques and continual refinement, the ICA feature ensures that Ditana Assistant can deliver high-quality responses across a wide range of topics, maximizing the potential of the underlying AI model through structured, introspective reasoning, with or without external knowledge sources.\n\n## Example Sessions\n\n### Terminal command generation examples\n\n#### Terminal command example 1 (using gpt-3.5-turbo)\n\n**Request:** _\"What are the largest files in the current directory and below?\"_\n\nIn this session, the user first inquires about the largest files in the current directory, then asks for suggestions on which of these might be deleted.\nThis example demonstrates that:\n - The assistant can provide ready-to-use terminal commands, including command chaining.\n - The assistant can analyze the output of invoked tools, supported by an automatic [contextual query](#maximizing-the-underlying-ai-models-potential).\n\n\u003e ```bash  \n\u003e ❯ ./ditana-assistant -a \"What are the largest files in the current directory and below?\"\n\u003e                                     is English: \"What are the largest files in the current directory and below?\"  \n\u003e                           refers to a computer: \"What are the largest files in the current directory and below?\"  \n\u003e   \n\u003e find . -type f -exec du -h {} + | sort -rh | head -n 10  \n\u003e Execute above command? (y/n) y  \n\u003e 364K\t./packaging/arch/ditana-assistant-1.036-1-any.pkg.tar.zst  \n\u003e 284K\t./src/ditana-logo.png  \n\u003e 284K\t./packaging/arch/pkg/ditana-assistant/usr/share/ditana/assistant/ditana-logo.png  \n\u003e 284K\t./packaging/arch/ditana-logo.png  \n\u003e 276K\t./.git/objects/21/e3382f3ee049d91368ce79218cb4049bae6222  \n\u003e 248K\t./myenv/lib/python3.12/site-packages/__pycache__/bottle.cpython-312.pyc  \n\u003e 248K\t./myenv/bin/__pycache__/bottle.cpython-312.pyc  \n\u003e 204K\t./myenv/lib/python3.12/site-packages/pip/_vendor/rich/__pycache__/_emoji_codes.cpython-312.pyc  \n\u003e 160K\t./myenv/lib/python3.12/site-packages/pip/_vendor/pkg_resources/__pycache__/__init__.cpython-312.pyc  \n\u003e 156K\t./myenv/lib/python3.12/site-packages/pip/_vendor/idna/__pycache__/uts46data.cpython-312.pyc  \n\u003e   \n\u003e Your Message ('enter' to quit): Which one of these are safe to delete?  \n\u003e                                     is English: \"Which one of these are safe to delete?\"  \n\u003e                   does not refer to a computer: \"Which one of these are safe to delete?\"  \n\u003e                 not suitable for Wolfram|Alpha: \"Which one of these are safe to delete?\"  \n\u003e                               contextual query: \"Which file in the list has the smallest size and can be safely deleted?\"  \n\u003e        Wolfram|Alpha declined contextual query: \"The input cannot be interpreted or no short answer is available.\"  \n\u003e                     answer to contextual query: \"The file with the smallest size in the list is:  ./myenv/lib/python3.12/site-packages/pip/_vendor...\"  \n\u003e ```  \n\u003e It is important to exercise caution when deleting files, especially system files or files related to applications. In the list provided,\nthe file that appears to be safe to delete without causing any major issues is:  \n\u003e `./myenv/lib/python3.12/site-packages/pip/_vendor/idna/__pycache__/uts46data.cpython-312.pyc`  \n\u003e This file seems to be a Python cache file and deleting it should not have a significant impact on the functionality of the application.\nHowever, it is always recommended to make a backup of the file before deleting it, in case it is needed later on.\n\n#### Terminal command example 2 (using gpt-3.5-turbo)\n\n**Request:** _\"Is the network name resolution service running stably?\"_\n\nIn this session, the user first inquires about the status of a service, then requests a summary. This example illustrates that:\n\n- The assistant can deduce the specific name of the service with the help of [System-Specific Context](#assistance-based-on-your-specific-system) (on Windows or macOS, the answer is different).\n- The assistant can analyze the output of invoked tools, supported by an automatic [contextual query](#maximizing-the-underlying-ai-models-potential) (see the following log).\n\n\u003e ```bash  \n\u003e ❯ ./ditana-assistant -a \"Is the network name resolution service running stably?\"   \n\u003e                                     is English: \"Is the network name resolution service running stably?\"  \n\u003e                           refers to a computer: \"Is the network name resolution service running stably?\"  \n\u003e   \n\u003e systemctl status systemd-resolved.service  \n\u003e Execute above command? (y/n) y  \n\u003e ● systemd-resolved.service - Network Name Resolution  \n\u003e      Loaded: loaded (/usr/lib/systemd/system/systemd-resolved.service; enabled; preset: enabled)  \n\u003e      Active: active (running) since Mon 2024-09-23 10:16:39 CEST; 3 days ago  \n\u003e  Invocation: 1e937e9c439a4fed968ce8d0e976e201  \n\u003e        Docs: man:systemd-resolved.service(8)  \n\u003e              man:org.freedesktop.resolve1(5)  \n\u003e              https://systemd.io/WRITING_NETWORK_CONFIGURATION_MANAGERS  \n\u003e              https://systemd.io/WRITING_RESOLVER_CLIENTS  \n\u003e    Main PID: 737 (systemd-resolve)  \n\u003e      Status: \"Processing requests...\"  \n\u003e       Tasks: 1 (limit: 154223)  \n\u003e      Memory: 11.8M (peak: 15M)  \n\u003e         CPU: 55.832s  \n\u003e      CGroup: /system.slice/systemd-resolved.service  \n\u003e              └─737 /usr/lib/systemd/systemd-resolved  \n\u003e   \n\u003e Sep 23 10:16:39 akino systemd[1]: Starting Network Name Resolution...  \n\u003e Sep 23 10:16:39 akino systemd-resolved[737]: Positive Trust Anchors:  \n\u003e Sep 23 10:16:39 akino systemd-resolved[737]: . IN DS 20326 8 2 e06d44b80b8f1d39a95c0b0d7c65d08458e880409bbc683457104237c7f8ec8d  \n\u003e Sep 23 10:16:39 akino systemd-resolved[737]: Negative trust anchors: home.arpa 10.in-addr.arpa 16.172.in-addr.arpa 17.172.in-addr.arpa 18.172.in-addr.arpa 19.172.in-addr.arpa 20.172.in-addr.arpa 21.172.in-addr.arpa 22.172.in-addr.arpa 23.172.in-addr.arpa 24.172.in-addr.arpa 25.172.in-addr.arpa 26.172.in-addr.arpa 27.172.in-addr.arpa 28.172.in-addr.arpa 29.172.in-addr.arpa 30.172.in-addr.arpa 31.172.in-addr.arpa 170.0.0.192.in-addr.arpa 171.0.0.192.in-addr.arpa 168.192.in-addr.arpa d.f.ip6.arpa …  \n\u003e Sep 23 10:16:39 akino systemd-resolved[737]: Using system hostname 'akino'.  \n\u003e Sep 23 10:16:39 akino systemd[1]: Started Network Name Resolution.  \n\u003e Sep 23 10:16:43 akino systemd-resolved[737]: enp5s0: Bus client set search domain list to: fritz.box  \n\u003e Sep 23 10:16:43 akino systemd-resolved[737]: enp5s0: Bus client set default route setting: yes  \n\u003e Sep 23 10:16:43 akino systemd-resolved[737]: enp5s0: Bus client set DNS server list to: 192.168.178.1  \n\u003e Hint: Some lines were ellipsized, use -l to show in full.  \n\u003e    \n\u003e Your Message ('enter' to quit): Can you please summarize this?  \n\u003e                                     is English: \"Can you please summarize this?\"  \n\u003e                   does not refer to a computer: \"Can you please summarize this?\"  \n\u003e                 not suitable for Wolfram|Alpha: \"Can you please summarize this?\"  \n\u003e                               contextual query: \"What is the total number of positive trust anchors listed in the output provided?\"  \n\u003e        Wolfram|Alpha declined contextual query: \"The input cannot be interpreted or no short answer is available.\"  \n\u003e                     answer to contextual query: \"There is a total of 1 positive trust anchor listed in the output provided.\"  \n\u003e ```  \n\u003e The output shows that the systemd-resolved service is active and running stably since September 23, 2024.\nIt is processing requests and has a main PID of 737. The service is managing network name resolution and has a positive trust anchor listed.\nThe system hostname is 'akino' and the service has set search domain list and DNS server list for the network interface enp5s0.\n\n### Introspective Contextual Augmentation (ICA) examples\n\n#### ICA example 1 (using gpt-3.5-turbo and Wolfram|Alpha)\n\n**Request:** _\"What should I wear today for a travel to New York?\"_\n\nThe response without ICA lacks specific information about today’s weather.\nBut even without ICA, if Wolfram|Alpha is configured, Ditana Assistant will always assess whether the request is directly suitable for Wolfram|Alpha\n(which it is not in this case). Here, Ditana Assistant’s [System-Specific Context](#assistance-based-on-your-specific-system) proves helpful.\nIt provides a more informed answer than one without even knowing the current month.\n\nThe second response, with [ICA](#maximizing-the-underlying-ai-models-potential) enabled, automatically utilizes **real-time information** from Wolfram|Alpha to check the current temperature in New York.\n\n##### Without ICA (default)\n\n\u003e ```bash  \n\u003e ❯ ./ditana-assistant \"What should I wear today for a travel to New York?\"  \n\u003e                                     is English: \"What should I wear today for a travel to New York?\"  \n\u003e                   does not refer to a computer: \"What should I wear today for a travel to New York?\"  \n\u003e                 not suitable for Wolfram|Alpha: \"What should I wear today for a travel to New York?\"  \n\u003e ```  \n\u003e I recommend wearing comfortable and stylish clothing for your travel to New York. Since it's September, you may want to consider layering options as the weather can be unpredictable. A light jacket or sweater, comfortable jeans or pants, and comfortable shoes for walking are good choices. Don't forget to check the weather forecast for New York to ensure you are prepared for any conditions. Safe travels!\n\n##### With ICA\n\u003e ```bash  \n\u003e ❯ ./ditana-assistant -a \"What should I wear today for a travel to New York?\"  \n\u003e                                     is English: \"What should I wear today for a travel to New York?\"  \n\u003e                   does not refer to a computer: \"What should I wear today for a travel to New York?\"  \n\u003e                 not suitable for Wolfram|Alpha: \"What should I wear today for a travel to New York?\"  \n\u003e                               contextual query: \"What is the average temperature in New York City on September 26th, 2024?\"  \n\u003e     Wolfram|Alpha’s answer to contextual query: \"On Thursday, 26 September 2024, the mean temperature in New York City, United States, was 21 degr...\"  \n\u003e ```  \n\u003e For a trip to New York City on September 26th, 2024, you may want to wear comfortable clothing suitable for a temperature of around 21 degrees Celsius. It's always a good idea to bring layers, as the weather can change throughout the day. Additionally, consider bringing an umbrella or rain jacket as there may be a chance of rain. Enjoy your trip!\n\n#### ICA example 2 (using gemma-2-2b-it-Q6_K.gguf with adaptive contextual queries)\n\n**Request:** _\"A ladder leaning against a wall reaches 4 meters up the wall. The bottom of the ladder is 3 meters from the wall. What is the angle between the ladder and the ground?\"_\n\nA [detailed analysis by ChatGPT-o1](https://chatgpt.com/share/66f53751-4694-8009-ba49-5da7c2560253) on the quality of the following two responses shows that Ditana Assistant’s [ICA](#maximizing-the-underlying-ai-models-potential) can avoid fundamental errors in the output:\n\n\u003e - Answer 2 is correct, and it demonstrates a proper understanding and application of trigonometric functions, with all intermediate steps accurately calculated.  \n\u003e - Answer 1, while partially correct in its calculation, contains a **fundamental error** in explaining the trigonometric relationships and does not provide the final numerical value of the angle.  \n\nSee [public link to the comparison](https://chatgpt.com/share/66f53751-4694-8009-ba49-5da7c2560253) for the full picture.\n\n##### Without ICA (default)\n\u003e ```bash  \n\u003e ❯ ./ditana-assistant \"A ladder leaning against a wall reaches 4 meters up the wall. The bottom of the ladder is 3 meters from the wall. What is the angle between the ladder and the ground?\"                   \n\u003e                                     is English: \"A ladder leaning against a wall reaches 4 meters up the wall. The bottom of the ladder is 3 meter...\"  \n\u003e                   does not refer to a computer: \"A ladder leaning against a wall reaches 4 meters up the wall. The bottom of the ladder is 3 meter...\"  \n\u003e ```  \n\u003e Here's how to solve this problem using trigonometry:\n\u003e \n\u003e **Understanding the Problem**  \n\u003e * We have a right triangle formed by the ladder, the wall, and the ground.  \n\u003e * The ladder is the hypotenuse (the longest side).  \n\u003e * The distance from the wall to the base of the ladder is one leg.  \n\u003e * The angle between the ladder and the ground is what we need to find.\n\u003e \n\u003e **Using Trigonometry**  \n\u003e The trigonometric function that relates the opposite side, adjacent side, and hypotenuse is the **tangent** (tan).  \n\u003e * **tan(angle) = opposite / adjacent**  \n\u003e **Applying the Information**  \n\u003e 1. **Opposite:** The ladder reaches 4 meters up the wall, so the opposite side is 4 meters.  \n\u003e 2. **Adjacent:** The base of the ladder is 3 meters from the wall, so the adjacent side is 3 meters.\n\u003e \n\u003e **Calculating the Angle**  \n\u003e * tan(angle) = 4 / 3  \n\u003e * angle = arctan(4/3)\n\u003e \n\u003e **Using a Calculator**  \n\u003e You can use a calculator to find the arctangent of 4/3. The result will be the angle in degrees.\n\u003e \n\u003e **Important Note:**  The angle will be an acute angle (less than 90 degrees).   \n\u003e Let me know if you'd like me to calculate the angle using a specific calculator!  \n\n##### With ICA\n\u003e ```bash  \n\u003e ❯ ./ditana-assistant -a \"A ladder leaning against a wall reaches 4 meters up the wall. The bottom of the ladder is 3 meters from the wall. What is the angle between the ladder and the ground?\"  \n\u003e                              is English: \"A ladder leaning against a wall reaches 4 meters up the wall. The bottom of the ladder is 3 meter...\"  \n\u003e            does not refer to a computer: \"A ladder leaning against a wall reaches 4 meters up the wall. The bottom of the ladder is 3 meter...\"  \n\u003e                        contextual query: \"What is the angle between the ladder and the ground, given the ladder's height is 4 meters and it...\"  \n\u003e Wolfram|Alpha declined contextual query: \"The input cannot be interpreted or no short answer is available.\"  \n\u003e              answer to contextual query: \"Here's how to solve this problem using trigonometry:  **Understanding the Problem**  * We have a ...\"  \n\u003e ```  \n\u003e   \n\u003e Here's how to solve this problem:  \n\u003e    \n\u003e **Understanding the Problem**  \n\u003e   \n\u003e * We have a right triangle formed by the ladder, the ground, and the wall.  \n\u003e * The ladder is the hypotenuse (the longest side).  \n\u003e * The distance from the wall to the base of the ladder is one leg.  \n\u003e * The height the ladder reaches on the wall is the other leg.  \n\u003e   \n\u003e **Using Trigonometry**  \n\u003e   \n\u003e We can use the sine function to find the angle:  \n\u003e   \n\u003e * **sin(angle) = opposite side / hypotenuse**  \n\u003e   \n\u003e In our case:  \n\u003e   \n\u003e * Opposite side = height of the ladder = 4 meters  \n\u003e * Hypotenuse = length of the ladder = unknown  \n\u003e * We need to find the angle (angle)  \n\u003e   \n\u003e **Solving for the Angle**  \n\u003e   \n\u003e 1. **Substitute the values:** sin(angle) = 4 meters / hypotenuse   \n\u003e 2. **Use the Pythagorean theorem:**  hypotenuse² = base² + height²  \n\u003e    *  hypotenuse² = 3 meters² + 4 meters²  \n\u003e    *  hypotenuse² = 25 meters²  \n\u003e    *  hypotenuse = √25 meters² = 5 meters  \n\u003e 3. **Substitute the hypotenuse back into the sine equation:** sin(angle) = 4 meters / 5 meters  \n\u003e 4. **Solve for the angle:** angle = arcsin(4/5)   \n\u003e 5. **Calculate the angle:** angle ≈ 53.13 degrees  \n\u003e   \n\u003e **Answer:** The angle between the ladder and the ground is approximately 53.13 degrees.   \n\u003e   \n\u003e Let me know if you have any other geometry problems!\n\n#### ICA example 3 (using gpt-3.5-turbo with automatic contextual queries)\n\n**Request:** _\"Can you explain how the proof-of-stake consensus mechanism differs from proof-of-work in blockchain technology?\"_\n\nA [detailed analysis of ChatGPT-o1](https://chatgpt.com/share/66f52038-c510-8009-b5ed-be61814b63be) on the quality of the following two responses indicates that Ditana Assistant’s [ICA](#maximizing-the-underlying-ai-models-potential) can better leverage the capabilities of the underlying LLM model:\n\n\u003e Between the two answers, Answer 2 is of higher quality. It offers a **more comprehensive and structured** comparison of the proof-of-stake and proof-of-work consensus mechanisms. By organizing the information into key points, it enhances readability and makes it easier to understand the distinct differences. Additionally, Answer 2 covers **extra dimensions** such as centralization and the economic incentives that promote security in PoS, providing a **more thorough explanation** that directly relates to the question.\n\nSee [public link to the detailed comparison](https://chatgpt.com/share/66f52038-c510-8009-b5ed-be61814b63be) for the full picture.\n\n##### Without ICA (default)\n\u003e ```bash  \n\u003e ❯ ./ditana-assistant \"Can you explain how the proof-of-stake consensus mechanism differs from proof-of-work in blockchain technology?\"  \n\u003e                     is English: \"Can you explain how the proof-of-stake consensus mechanism differs from proof-of-work in blockcha...\"  \n\u003e   does not refer to a computer: \"Can you explain how the proof-of-stake consensus mechanism differs from proof-of-work in blockcha...\"  \n\u003e not suitable for Wolfram|Alpha: \"Can you explain how the proof-of-stake consensus mechanism differs from proof-of-work in blockcha...\"  \n\u003e ```  \n\u003e Certainly! In blockchain technology, both proof-of-stake (PoS) and proof-of-work (PoW) are consensus mechanisms used to validate transactions and secure the network.   \n\u003e   \n\u003e Proof-of-work requires miners to solve complex mathematical puzzles in order to validate transactions and create new blocks. This process is energy-intensive and requires significant computational power. Miners compete to solve these puzzles, and the first one to do so is rewarded with newly minted cryptocurrency.  \n\u003e   \n\u003e On the other hand, proof-of-stake does not require miners to solve complex puzzles. Instead, validators are chosen to create new blocks based on the amount of cryptocurrency they hold and are willing to \"stake\" as collateral. Validators are selected to create new blocks based on various factors, such as the amount of cryptocurrency they hold and how long they have been staking it.  \n\u003e   \n\u003e One key difference between PoS and PoW is the energy consumption. PoW requires a significant amount of energy to solve the puzzles, leading to concerns about its environmental impact. PoS, on the other hand, is considered to be more energy-efficient since it does not require the same level of computational power.  \n\u003e   \n\u003e Additionally, PoS is often seen as more secure and resistant to certain types of attacks, such as the 51% attack, where a single entity controls the majority of the network's mining power. In PoS, an attacker would need to control the majority of the cryptocurrency supply to carry out a similar attack.  \n\u003e   \n\u003e Overall, both PoW and PoS have their own advantages and disadvantages, and the choice between the two consensus mechanisms often depends on the specific goals and requirements of the blockchain network.  \n\n##### With ICA\n\u003e ```bash  \n\u003e ❯ ./ditana-assistant -a \"Can you explain how the proof-of-stake consensus mechanism differs from proof-of-work in blockchain technology?\"  \n\u003e                              is English: \"Can you explain how the proof-of-stake consensus mechanism differs from proof-of-work in blockcha...\"  \n\u003e            does not refer to a computer: \"Can you explain how the proof-of-stake consensus mechanism differs from proof-of-work in blockcha...\"  \n\u003e          not suitable for Wolfram|Alpha: \"Can you explain how the proof-of-stake consensus mechanism differs from proof-of-work in blockcha...\"  \n\u003e                        contextual query: \"How does the energy consumption of the proof-of-stake consensus mechanism compare to that of proo...\"  \n\u003e Wolfram|Alpha declined contextual query: \"The input cannot be interpreted or no short answer is available.\"  \n\u003e              answer to contextual query: \"The energy consumption of the proof-of-stake consensus mechanism is significantly lower compared ...\"  \n\u003e ```  \n\u003e Certainly! Here are the key differences between the proof-of-stake (PoS) and proof-of-work (PoW) consensus mechanisms in blockchain technology:  \n\u003e   \n\u003e 1. **Validation Process**:  \n\u003e    - In PoW, miners compete to solve complex mathematical puzzles in order to validate transactions and create new blocks on the blockchain. The first miner to solve the puzzle gets to add the new block to the blockchain.  \n\u003e    - In PoS, validators are chosen to create new blocks based on the amount of cryptocurrency they hold and are willing to \"stake\" as collateral. Validators are selected based on various factors such as the amount of cryptocurrency they hold and how long they have been staking.  \n\u003e  \n\u003e 2. **Energy Consumption**:  \n\u003e    - PoW requires a significant amount of computational power and electricity to solve the mathematical puzzles, leading to high energy consumption. This has raised concerns about the environmental impact of PoW blockchains.  \n\u003e    - PoS is much more energy-efficient as it does not rely on mining and the energy-intensive process of solving puzzles. Validators are chosen based on their stake in the network, reducing the overall energy consumption of the blockchain.  \n\u003e   \n\u003e 3. **Security**:  \n\u003e    - PoW is considered to be secure due to the computational power required to solve the puzzles. The idea is that an attacker would need to control a majority of the network's computational power to manipulate the blockchain.  \n\u003e    - PoS is also considered secure, as validators have a financial stake in the network. If they validate fraudulent transactions, they risk losing their stake, providing an economic incentive to act honestly.  \n\u003e  \n\u003e 4. **Centralization**:  \n\u003e    - PoW has been criticized for centralization tendencies, as mining pools with significant computational power can dominate the network.    \n\u003e   - PoS is often seen as more decentralized, as validators are chosen based on their stake in the network rather than computational power.  \n\u003e   \n\u003e Overall, PoS is seen as a more energy-efficient and environmentally friendly alternative to PoW, while still maintaining security and decentralization in blockchain networks.  \n\n## Collaboration\n\nWe welcome contributions from the community to help improve and expand Ditana Assistant.\nPlease check our [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on how to submit issues, pull requests, and more.\n\n## Sponsorship\n\nDitana Assistant is an open-source project that relies on community support.\nIf you find this project valuable and would like to support its ongoing development, please consider becoming a sponsor.\nAt the [top right of this page](https://github.com/acrion/ditana-assistant), GitHub automatically displays links to various funding platforms, which also provide more background information about me.\n\nYour sponsorship helps me to:\n- Dedicate more time to developing new features\n- Maintain and improve existing functionality\n- Provide better documentation and support\n- Cover operational costs associated with hosting and distribution\n\nThank you for your support!\n\n## Current Project Status\n\nDitana Assistant is currently in active development. Here’s an overview of its current status across different platforms and features:\n\n### Platform Support\n\n- **Linux**: Primary development and testing platform. Most features are fully functional and well-tested.\n\n- **Windows**: Basic functionality has been implemented and tested, including command generation for `cmd.exe` and `PowerShell`.\n  However, comprehensive testing across different Windows versions is still ongoing.\n  Some features may have limited functionality or require further optimization.\n\n- **macOS**: Initial development has begun, but thorough testing has not yet been conducted.\n  Expect potential issues and limitations when running on macOS.\n\n### Ongoing and Future Development\n\n- **Installer Availability**: The Ditana Assistant installer packages for macOS, Windows, and other Linux distributions (such as Debian and Fedora) are under active development. For these platforms, users are currently required to install Ditana Assistant from source using [Poetry](https://python-poetry.org). This involves running terminal-based commands to set up a virtual environment and install dependencies as described in the [Installation](#installation) section. We aim to provide native installers and packages for a more seamless installation experience in future releases.\n\n- **Multimodal Integration**: Future iterations of Ditana Assistant will focus on multimodal support, enabling contextual guidance by analyzing screenshots or controlling the mouse pointer for computer operation. By integrating visual recognition and advanced automation, the assistant will provide more intuitive, hands-free support. The goal of this development is to extend the capabilities of the Assistant from text-based prompts to comprehensive on-screen interaction, thereby increasing user efficiency and accuracy.\n\n- **Unit Testing**: The number of unit tests in `input_analyzers_ai_test.py` is currently insufficient. We particularly need more tests for:\n  - Cases where the assistant incorrectly identifies (or fails to identify) prompts suitable for terminal command generation.\n  - Scenarios in which terminal commands are mistakenly suggested for normal prompts.\n  We encourage users to submit pull requests with additional test cases, especially for edge cases they encounter.\n\n- **Wolfram|Alpha Integration**: While basic integration is implemented for mathematical calculations and obvious real-time queries (e.g., weather information), this feature can be significantly expanded.\n  Wolfram|Alpha offers extensive factual knowledge across various domains, which could enhance the assistant's contextual understanding. Currently, there are no unit tests for this feature.\n\n- **Introspective Contextual Augmentation (ICA)**: This feature is thoroughly developed and rigorously tested.\nIts effectiveness has been validated through comprehensive, standardized tests for statistical significance,\nas detailed in the [Statistical Evaluation and Optimization](#statistical-evaluation-and-optimization) section.\nWhile proven effective, there are numerous ideas for further enhancements, outlined in the [Experimentation and Further Development](#experimentation-and-further-development) section.\nFor a complete overview, see the [Introspective Contextual Augmentation](#introspective-contextual-augmentation-ica) section.\n\nWe are actively working on improving cross-platform compatibility, expanding features, and enhancing overall reliability. We welcome contributions, especially in the form of testing, feedback, and pull requests for all environments and features.\n\nPlease note that while we strive for stability, Ditana Assistant is still evolving, and you may encounter bugs or unexpected behavior, particularly on less-tested platforms or with experimental features. We appreciate your patience and encourage you to report any issues you encounter.\n\n## Important Notes\n\n- The assistant may suggest terminal commands, which are only executed after user confirmation.\n- Due to the use of LLMs, there’s a possibility of errors. Always review suggested commands before execution.\n- When using the local KoboldCpp server, the [Instruct Tag Format](https://ai.google.dev/gemma/docs/formatting) is optimized for the Gemma language model.\n- API Usage and Performance:\n  - Ditana Assistant may send multiple API requests per user prompt, depending on which features are enabled in `config.py` (see [Core Functionality Settings](#core-functionality-settings)). Key features affecting API usage include:\n    - `generate_terminal_cmd`\n    - `wolfram_alpha_short_answers_app_id`\n  - Using the `-a` or `--augmentation` command-line option significantly increases the number of API calls (see [Command-line Interface](#command-line-interface)).\n  - More API calls result in longer response times and potentially higher costs for paid services like OpenAI.\n    As of October 2024, the cost for OpenAI's `gpt-4-mini` model is [$0.150 / 1M input tokens](https://openai.com/api/pricing).\n\nWe are committed to continuously improving Ditana Assistant’s performance, accuracy, and feature set.\nYour feedback and contributions are invaluable in this process.\n\n## Feedback and Support\n\nYour insights are crucial to shaping Ditana Assistant’s future. We invite you to share your feedback, report issues, and engage with other users in our [Ditana Assistant Discord channel](https://discord.gg/A3CdBXxush). Join our community to collaborate, ask questions, and stay updated with the latest developments.\n\n## Licensing\n\nDitana Assistant is dual-licensed:\n\n1. AGPL v3 or later for open-source use.\n2. Commercial licensing available for closed-source integration (or other deviations from the AGPL v3 license).\n\nWe would like to emphasize that offering a dual license does not restrict users of the normal open-source license (including commercial users).\nThe dual licensing model is designed to support both open-source collaboration and commercial integration needs.\nFor commercial licensing inquiries, please contact us at [https://acrion.ch/sales](https://acrion.ch/sales).\n\n## Author\n\nCopyright © 2024, 2025 Stefan Zipproth, acrion innovations GmbH, Switzerland\n[https://ditana.org](https://ditana.org)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Facrion%2Fditana-assistant","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Facrion%2Fditana-assistant","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Facrion%2Fditana-assistant/lists"}