Zammad-AI

GenAI-powered agent for Zammad

Zammad-AI is a Python-based microservice that integrates Generative AI capabilities into the Zammad ticketing system. It operates as an event-driven service, listening to ticket events via Kafka and generating AI-assisted responses.

🚀 Features

• Event-Driven Architecture: Built with FastStream and Kafka for robust message processing.
• Smart Filtering: Configurable filtering of ticket events based on request types.
• Secure Communication: Supports mTLS for secure Kafka connections using truststore.
• Modern Stack: Powered by Python 3.13, Pydantic, and uv.
• Configurable: Flexible configuration via YAML, .env, and environment variables.

🛠️ Architecture

1. Ingest: Listens to the ticket-events Kafka topic.
2. Filter: Validates events based on configured valid_request_types.
3. Process: Fetches ticket details and generates an AI response (GenAI integration).
4. Output: Posts the draft response back to Zammad.

📋 Prerequisites

• Python: 3.13+
• Package Manager: uv
• Docker: For running the local development stack.

⚙️ Configuration

Configuration is managed via pydantic-settings. The application looks for configuration in the following order (highest priority first):

1. Environment Variables (prefix ZAMMAD_AI_)
2. config.yaml
3. .env file
4. Defaults

Key Settings

Setting	Env Variable	Description	Default
kafka.broker_url	ZAMMAD_AI_KAFKA__BROKER_URL	Kafka broker URL	localhost:9092
kafka.topic	ZAMMAD_AI_KAFKA__TOPIC	Kafka topic to listen to	ticket-events
valid_request_types	ZAMMAD_AI_VALID_REQUEST_TYPES	List of valid request types	Required

Example config.yaml:

kafka:
  broker_url: "localhost:9092"
  topic: "ticket-events"

valid_request_types:
  - "general_inquiry"
  - "support"

🏃‍♂️ Running Locally

1. Start Infrastructure

Start the local Kafka broker, Zookeeper, and Mailpit using Docker Compose:

docker compose up -d

• Kafka UI: http://localhost:8089
• Mailpit: http://localhost:8025

2. Install Dependencies

Use uv to install the project dependencies:

uv sync

3. Run the Service

Run the application:

uv run python zammad-ai/main.py

🧪 Testing

Run the test suite using pytest:

uv run pytest

💻 Development

Linting & Formatting

The project uses ruff for linting and formatting.

Check for issues:

uv run ruff check .

Format code:

uv run ruff format .

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please open an issue with the tag "enhancement", fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Open an issue with the tag "enhancement"
2. Fork the Project
3. Create your Feature Branch (git checkout -b feature/AmazingFeature)
4. Commit your Changes (git commit -m 'Add some AmazingFeature')
5. Push to the Branch (git push origin feature/AmazingFeature)
6. Open a Pull Request

More about this in the CODE_OF_CONDUCT file.

License

Distributed under the MIT License. See LICENSE file for more information.

Contact

it@M - opensource@muenchen.de