GitHub Copilot - Zammad-AI Python Service

Development instructions for the Zammad-AI Python service: a GenAI-powered agent for the Zammad ticketing system.

Project Overview

Zammad-AI is a Python-based service that integrates GenAI capabilities into the Zammad ticketing system. It operates as a Kafka consumer, reacting to ticket events to provide AI-assisted responses.

Architecture & Core Concepts

1. **Ingest**: Listens to `ticket-events` Kafka topic

2. **Filter**: Validates events based on `request_type` (mapped from `anliegenart`)

3. **Process**: (Future) Fetches ticket details via Zammad API, generates AI response

4. **Output**: (Future) Posts draft response back to Zammad

Instructions

When working on this codebase, follow these guidelines:

1. Dependency Management

2. Running the Application

**Start Local Development Stack:**

```bash

docker compose up -d

```

This starts:

**Start the Service:**

```bash

uv run python zammad-ai/main.py

```

The service will:

3. Testing

**Kafka Testing Pattern:**

Use `faststream.kafka.TestKafkaBroker` for in-memory broker testing:

```python

from faststream.kafka import TestKafkaBroker

async with TestKafkaBroker(broker) as test_broker:

await test_broker.publish(topic=settings.kafka.topic, message=message)

# Add assertions here

```

Reference `zammad-ai/test/test_kafka.py` for examples.

4. Code Conventions

**Kafka Integration:**

**Configuration Access:**

```python

from app.core.settings import get_settings

settings = get_settings()

Access nested config: settings.kafka.topic

```

Configuration hierarchy (highest to lowest precedence):

1. Environment variables (prefix `ZAMMAD_AI_`)

2. `.env` file

3. `config.yaml`

**Logging:**

```python

from app.utils.logging import getLogger

logger = getLogger("zammad-ai")

logger.info("Your message here")

```

5. Linting & Formatting

Key Files

Development Tips

1. **Configuration Changes**: After modifying `app/core/settings.py`, restart the service to pick up changes

2. **Event Schema**: Always validate Kafka message schemas match the `Event` model before processing

3. **Error Handling**: Use explicit Kafka message acknowledgment (`AckMessage`/`NackMessage`) to control retry behavior

4. **Testing**: Write tests using the `TestKafkaBroker` pattern before implementing event handlers

5. **Security**: When configuring mTLS, ensure certificates are properly referenced in settings and mounted in containers