handmark 0.3.2.1

Handnotes to markdown in seconds

Handmark

Handmark is a Python CLI tool that converts handwritten notes from images into Markdown files. It uses Azure AI to process images and extract text, making it easy to digitize handwritten content.

---

Features

• 🖼️ Image to Markdown Conversion - Transform handwritten notes from images into clean, formatted Markdown
• 🧠 Intelligent Title Extraction - Automatically detects and extracts titles from content for smart file naming
• ⚡ Easy CLI Interface - Simple, intuitive commands with rich console output and error handling
• 🤖 Azure AI Integration - Leverages Azure AI models for accurate handwriting recognition
• 🔧 Model Configuration - Choose from multiple AI models and save your preferences
• 🔐 Secure Authentication - GitHub token-based authentication with secure local storage
• 📁 Flexible Output - Customize output directory and filename options

---

Quick Start

1. Install Handmark:

   pip install handmark
   

2. Configure authentication:

   handmark auth
   

3. Process your first image:

   handmark digest path/to/your/image.jpg
   

That's it! Your handwritten notes will be converted to a Markdown file.

---

Installation

Requirements

• Python 3.10 or higher
• A GitHub token (for Azure AI access)

Install from PyPI

pip install handmark

Install with uv (recommended)

uv pip install handmark

Install from source

git clone https://github.com/devgabrielsborges/handmark.git
cd handmark
pip install -e .

---

Usage

Getting Started

Before processing images, you need to configure authentication:

handmark auth

This will prompt you to enter your GitHub token, which provides access to Azure AI services.

Commands Overview

Command	Description
handmark digest <image>	Convert handwritten image to Markdown
handmark auth	Configure GitHub token authentication
handmark conf	Select and configure AI model
handmark --version	Show version information

Process an Image

handmark digest <image_path> [options]

Options:

• -o, --output <directory> - Specify output directory (default: current directory)
• --filename <name> - Custom output filename (default: response.md)

Examples:

# Basic usage - process image and save to current directory
handmark digest samples/prova.jpeg

# Custom output directory
handmark digest samples/prova.jpeg -o ./notes

# Custom filename
handmark digest samples/prova.jpeg --filename lecture-notes.md

# Both custom directory and filename
handmark digest samples/prova.jpeg -o ./outputs --filename my-notes.md

Supported Image Formats

Handmark supports common image formats including:

• JPEG/JPG
• PNG
• And other formats supported by Azure AI Vision

Configure Authentication

handmark auth

This will prompt you to enter your GitHub token, which is required for Azure AI integration. The token is securely stored in a .env file in the project directory.

Configure Model

handmark conf

This command lets you select and configure the AI model used for image processing. You can choose from available Azure AI models, and your selection will be saved for future runs. If no model is configured, the system will use a default model.

Check Version

handmark --version

---

Example

Here's a real-world example of Handmark in action:

Input image (samples/prova.jpeg):

Output (prova-response.md):

# Primeiro Exercício Escolar - 2025.1

Leia atentamente todas as questões antes de começar a prova. As respostas obtidas somente terão validade se respondidas nas folhas entregues. Os cálculos podem ser escritos a lápis e em qualquer ordem. Evite usar material eletrônico durante a prova, não sendo permitido o uso de calculadora programável para validá-lo. Não é permitido o uso de celular em sala.

---

1. (2 pontos) Determine a equação do plano tangente à função f(x,y) = √(20 - x² - 7y²) em (2,1). Em seguida, calcule um valor aproximado para f(1.9, 1.1).

2. (2 pontos) Determine a derivada direcional de f(x,y) = (xy)^(1/2) em P(2,2), na direção de Q(5,4).

3. (2 pontos) Determine e classifique os extremos de f(x,y) = x⁴ + y⁴ - 4xy + 2.

4. (2 pontos) Usando integrais duplas, calcule o volume acima de onde z = 0 e abaixo da superfície z = x² + y² + 2.

5. (2 pontos) Sabendo que E é o volume do sólido delimitado pelo cilindro parabólico z = x² + y² e pelo plano z = 1, apresente um esboço deste volume e calcule o valor de E.

The output is saved as a Markdown file with a filename derived from the detected title.

[See the full example output](prova-response.md)

---

## Troubleshooting

### Common Issues

**Authentication Error:**

Error: GitHub token not configured or invalid

**Solution:** Run `handmark auth` to configure your GitHub token.

**Image Format Error:**

Error: Unsupported image format

**Solution:** Ensure your image is in a supported format (JPEG, PNG, etc.).

**No Model Configured Warning:**

No model configured. Using default model

**Solution:** Run `handmark conf` to select your preferred AI model.

### Getting Help

- Check the [issues page](https://github.com/devgabrielsborges/handmark/issues) for known problems
- Create a new issue if you encounter a bug
- Use `handmark --help` for command-line help

---

## Development

### Prerequisites

- Python 3.10 or higher
- A GitHub token for Azure AI integration
- `uv` (recommended) or `pip` for package management

### Setup

1. **Clone the repository:**
   ```bash
   git clone https://github.com/devgabrielsborges/handmark.git
   cd handmark

2. Install dependencies:

   # Using uv (recommended)
   uv pip install -e .
   
   # Or using pip
   pip install -e .
   

3. Configure for development:

   handmark auth  # Configure your GitHub token
   handmark conf  # Select preferred AI model
   

Project Structure

• src/ - Source code
  • main.py - CLI interface and command handlers
  • dissector.py - Image processing and Azure AI API interaction
  • model.py - AI model management and configuration
  • utils.py - Helper functions and utilities
• samples/ - Sample images for testing and demonstration
• tests/ - Comprehensive unit tests
• .github/ - GitHub workflows and project instructions

---

---

Contributing

Contributions are welcome! Please feel free to:

• Open an issue for bug reports or feature requests
• Submit a pull request with improvements
• Help improve documentation
• Share examples of your handwritten notes processed with Handmark

Development Workflow

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests if applicable
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

---

License

This project is licensed under the MIT License - see the LICENSE file for details.

Author

• Gabriel Borges (@devgabrielsborges)

---

Last updated: May 29, 2025