README.md

---
title: fabric_to_espanso
app_file: gradio_app_query_only.py
sdk: gradio
sdk_version: 5.12.0
---
# Fabric to Espanso Converter

A Python application that bridges Fabric prompts with Espanso and Obsidian Textgenerator by managing and converting prompts through a vector database. It enables semantic search and efficient management of prompts while providing a modern web interface for easy interaction.
There's also a seperate gradio app that can be hosted on Hugging Face Spaces to provide a query-only interface.

## Features

- **Vector Database Integration**: Store and manage Fabric prompts in a Qdrant vector database with semantic search capabilities
- **Automated Conversion**: Convert stored prompts into Espanso YAML format for system-wide usage
- **Change Detection**: Automatically detect and process changes in the Fabric patterns folder
- **Web Interface**: Modern Gradio-based interface for easy prompt searching and management
- **Semantic Search**: Find relevant prompts based on their meaning, not just exact matches
- **Clipboard Integration**: Quick copying of prompts directly to clipboard
- **Logging System**: Comprehensive logging for tracking operations and debugging

## Prerequisites

- Python 3.11 or higher
- Fabric (https://github.com/danielmiessler/fabric)
- Qdrant vector database (local or cloud instance)
- Obsidian with TextGenerator plugin (https://github.com/obsidianmd/obsidian-textgenerator)
- Linux/WSL2 or Windows with WSL2

## Installation

1. **Environment Setup**:
   ```bash
   # Clone the repository
   git clone [repository-url]
   cd fabric_to_espanso

   # Install PDM if not already installed
   pip install pdm

   # Install dependencies
   pdm install
   ```

2. **Configuration**:
   - Copy `.env.example` to `.env`
   - Set your Qdrant API key in `.env`:
     ```
     QDRANT_API_KEY=your_api_key_here
     ```

3. **Obsidian Setup**:
   - Install Obsidian and the TextGenerator plugin
   - Create the folder structure:
     ```
     Extra/
     └── FabricPatterns/
         ├── Official/  # Official Fabric patterns
         └── Own/       # Custom patterns
     ```

4. **Fabric Setup**:
   - Install Fabric, see https://github.com/danielmiessler/fabric

5. **QDRANT Setup**:
   - Install Qdrant, see https://qdrant.io/en/
   - Start Qdrant server

6. **Parameters**:
   - Set all the parameters in the file `parameters.py`.

7. **Optional**:
   - Create a Powershell script to run the Streamlit app


## Usage

### Starting the Application

#### Linux/WSL2
```bash
# Start the Gradio interface
python gradio_app_query_only.py
```

#### Windows (with WSL2)
```powershell
# Use the provided PowerShell script
./start_app.ps1
```

### Core Operations

1. **Search Prompts**:
   - Enter your search query in the search box
   - Results are ranked by semantic similarity
   - Click on a result to view its contents

2. **Copy Prompts**:
   - Select a prompt from the results
   - Click "Copy to Clipboard" to copy the prompt text

3. **Update Database**:
   - Run `python main.py` to process changes in the Fabric patterns folder
   - New and modified prompts are automatically added to the database
   - Deleted prompts are removed from the database

## Project Structure

```
fabric_to_espanso/
├── src/
│   ├── fabrics_processor/    # Core processing logic
│   └── search_qdrant/        # Search functionality
├── gradio_app_query_only.py  # Web interface
├── main.py                   # CLI entry point
└── parameters.py            # Configuration parameters
```

## Dependencies

Core dependencies are managed through PDM:

- gradio >= 5.12.0
- qdrant-client >= 1.12.1
- fastembed >= 0.4.2
- python-dotenv
- pyperclip >= 1.9.0
- pyyaml >= 6.0.2
- regex >= 2024.11.6

## TODO

The following items need to be addressed to improve code quality, maintainability, and functionality:

### Database Optimization
- Check the database for any points with exactly the same vector or nearly the same. Remove those to reduce redundancy and improve search efficiency.

### Metadata Enhancement
- If available, use the readme.md file from the fabrics folder to fill the "purpose" field in the database entries.
- If readme.md is not available in the fabrics folder, create the "purpose" field from an LLM response that summarizes the goal of the fabric file.

### UI/UX Improvements
- Add a compare interface to the gradio app to allow side-by-side comparison of prompts.
- Remove the streamlit_only_query app as it's being replaced by the gradio interface.

### Code Refactoring
- Implement proper error handling for database operations.
- Add comprehensive logging throughout the application.
- Create unit tests for core functionality.
- Implement type hints consistently across all Python files.
- Add input validation for all user-provided data.
- Refactor the database operations into a dedicated class.
- Implement connection pooling for better database performance.
- Add docstrings to all functions and classes.
- Create a configuration class to handle all settings.
- Add proper cleanup of resources in error cases.

### Documentation
- Add API documentation for all public interfaces.
- Include examples for common use cases.
- Document the database schema and vector space organization.
- Add contribution guidelines.
- Include troubleshooting section.

### Security
- Implement proper environment variable handling.
- Add input sanitization for all user inputs.
- Implement rate limiting for the web interface.
- Add proper authentication for the web interface.

### Performance
- Implement caching for frequently accessed prompts.
- Optimize vector similarity search parameters.
- Add batch processing for large-scale operations.

## License

This project is licensed under the MIT License.