claia-zammad 0.0.1
CLAIA Zammad Extensions
Requires Python: >=3.12

# CLAIA Zammad Extension

A CLAIA extension providing tool modules for Zammad helpdesk integration, including ticket management and AI-assisted processing workflows.

- Website: https://claia.dev
- License: Apache-2.0
- Python: 3.12+

## Overview

This extension adds two tool modules to CLAIA for interacting with Zammad:

- **zammad** - Basic commands for listing, viewing, and managing tickets
- **zammad_processes** - AI-assisted workflows for tagging and account processing

## Installation

### From Source

```bash
# Clone the repository
git clone https://gitlab.com/exofox/claia/claia-zammad.git
cd claia-zammad

# Create virtual environment
python -m venv .venv
. .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -U pip
pip install -e .
```

### From PyPI

```bash
pip install claia-zammad
```

## Configuration

This extension requires the following configuration in your CLAIA settings:

- `zammad_api_token` - Your Zammad API token
- `zammad_base_url` - Your Zammad instance URL (e.g., `https://example.zammad.com`)
- `files_directory` - Directory for file operations

## Usage

After installation, the Zammad tool modules will be automatically registered in CLAIA.

### Basic Commands (zammad module)

```bash
# List open tickets
:zammad list

# List tickets with a specific query
:zammad list query=my-tickets

# Get ticket details
:zammad details ticket_id=123

# Add a tag to a ticket
:zammad tag_add ticket_id=123 tag=urgent

# Remove a tag from a ticket
:zammad tag_remove ticket_id=123 tag=resolved

# Find tickets by subject
:zammad find_subject subject="password reset"

# Delete tickets by subject (requires confirmation)
:zammad delete_subject subject="test ticket" confirm=true
```

### Process Commands (zammad_processes module)

```bash
# Process a single ticket with AI tagging
:zammad_processes process_single ticket_id=123

# Remove AI tags from a ticket
:zammad_processes untag_single ticket_id=123

# Batch process untagged tickets
:zammad_processes process_tag limit=10

# Remove AI tags from all tagged tickets
:zammad_processes process_untag limit=10

# Process account management tickets
:zammad_processes process_account output_file=accounts.txt limit=5

# Process a single account ticket
:zammad_processes process_account_single ticket_id=456
```

## Project Structure

```
claia-zammad/
├── src/
│   └── zammad/
│       ├── __init__.py
│       ├── api.py              # Zammad API client
│       ├── constants.py        # Queries and prompt templates
│       ├── plugin_basic.py     # Basic commands module
│       ├── plugin_processes.py # Process workflows module
│       ├── utils.py            # Formatting and AI utilities
│       └── README.md           # Module documentation
├── pyproject.toml              # Project config & entry points
├── deploy.sh                   # Deployment script
├── LICENSE
├── NOTICE
└── README.md
```

## Module Details

### API Client (`api.py`)

The `ZammadAPI` class provides HTTP-based access to Zammad:
- Ticket CRUD operations
- Article retrieval
- Tag management
- Search functionality

### Utilities (`utils.py`)

The `ZammadUtils` class handles:
- Ticket formatting for display
- AI-assisted tagging workflows
- Account processing pipelines

### Constants (`constants.py`)

Defines:
- Predefined ticket queries (open, closed, tagged, etc.)
- AI prompt templates for tagging and account processing

## Building and Distribution

### Build Wheel

```bash
pip install build
python -m build

# Or use the deploy script
./deploy.sh --build-whl
```

### Build Debian Package

```bash
./deploy.sh --build-deb
```

## Related Projects

- [CLAIA Website](https://claia.dev)
- [CLAIA](https://gitlab.com/exofox/claia/claia) - The main CLAIA framework
- [CLAIA Extension Template](https://gitlab.com/exofox/claia/claia-template) - Template for creating extensions

## Support

- Documentation: https://claia.dev
- Issues: https://gitlab.com/exofox/claia/claia-zammad/-/issues
- Main Project: https://gitlab.com/exofox/claia/claia

## License

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