Metadata-Version: 2.4
Name: dotagent-toolkit
Version: 0.2.1
Summary: CLI-Toolkit für AI-Agent-Infrastruktur: .agent-Ordner, Tool-Discovery, Credential-Management
Project-URL: Homepage, https://gitlab.com/mhennemeyer/dotagent
Project-URL: Repository, https://gitlab.com/mhennemeyer/dotagent
Project-URL: Issues, https://gitlab.com/mhennemeyer/dotagent/-/issues
Author: Matthias Hennemeyer
License-Expression: MIT
License-File: LICENSE
Keywords: agent,ai,cli,knowledgebase,tools
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: httpx>=0.24.0
Requires-Dist: openai>=1.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: tomli-w>=1.0.0
Requires-Dist: tomli>=2.0.0; python_version < '3.11'
Requires-Dist: typer>=0.9.0
Provides-Extra: all
Requires-Dist: beautifulsoup4>=4.12.0; extra == 'all'
Requires-Dist: ebooklib>=0.18; extra == 'all'
Requires-Dist: faiss-cpu>=1.7.0; extra == 'all'
Requires-Dist: httpx>=0.24.0; extra == 'all'
Requires-Dist: numpy>=1.24.0; extra == 'all'
Requires-Dist: openai>=1.0.0; extra == 'all'
Requires-Dist: pymupdf>=1.23.0; extra == 'all'
Requires-Dist: requests>=2.28.0; extra == 'all'
Provides-Extra: beuys
Requires-Dist: openai>=1.0.0; extra == 'beuys'
Provides-Extra: dev
Requires-Dist: beautifulsoup4>=4.12.0; extra == 'dev'
Requires-Dist: ebooklib>=0.18; extra == 'dev'
Requires-Dist: faiss-cpu>=1.7.0; extra == 'dev'
Requires-Dist: httpx>=0.24.0; extra == 'dev'
Requires-Dist: numpy>=1.24.0; extra == 'dev'
Requires-Dist: openai>=1.0.0; extra == 'dev'
Requires-Dist: pymupdf>=1.23.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: requests>=2.28.0; extra == 'dev'
Provides-Extra: envoy
Requires-Dist: requests>=2.28.0; extra == 'envoy'
Provides-Extra: kb
Requires-Dist: beautifulsoup4>=4.12.0; extra == 'kb'
Requires-Dist: ebooklib>=0.18; extra == 'kb'
Requires-Dist: faiss-cpu>=1.7.0; extra == 'kb'
Requires-Dist: numpy>=1.24.0; extra == 'kb'
Requires-Dist: openai>=1.0.0; extra == 'kb'
Requires-Dist: pymupdf>=1.23.0; extra == 'kb'
Provides-Extra: vision
Requires-Dist: httpx>=0.24.0; extra == 'vision'
Requires-Dist: openai>=1.0.0; extra == 'vision'
Description-Content-Type: text/markdown

# dotagent

[![PyPI version](https://badge.fury.io/py/dot-agent.svg)](https://pypi.org/project/dot-agent/)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

CLI-Toolkit für AI-Agent-Infrastruktur: `.agent`-Ordner, Tool-Discovery, Credential-Management, Knowledgebase, Vision-Tool und Bildgenerierung – alles in einem Paket.

## Quickstart

### 1. Installation

```bash
# Empfohlen: via pipx (isolierte Installation)
pipx install "dot-agent[all]"

# Oder via pip
pip install dot-agent          # Basis (CLI, init, tools, setup)
pip install "dot-agent[all]"   # Alles: Knowledgebase + Vision + Bildgenerierung
```

Oder via Repo:

```bash
# Aus dem Repository (Entwicklungsmodus)
git clone <repo-url>
cd dotagent
pip install -e ".[dev]"
```

### 2. Globales Setup

```bash
# Globalen ~/.agent/-Ordner mit Templates anlegen
dotagent init
```

Das erstellt `~/.agent/` mit `rules.md`, `functional.md`, `projects.md` und `config.toml`.

> **Sicher für bestehende Setups:** Bereits vorhandene Dateien werden *nie* überschrieben – nur fehlende Dateien werden angelegt. Der Output zeigt genau, was erstellt und was übersprungen wurde.

### 3. Credentials einrichten

```bash
# Status aller Credentials prüfen
dotagent setup --check

# Interaktiver Wizard für fehlende Credentials
dotagent setup

# Einzelnes Credential einrichten
dotagent setup openai
```

### 4. Projekt einrichten

```bash
cd mein-projekt

# Projektlokalen .agent/-Ordner anlegen
dotagent init .

# Mit Projektname (für ~/.agent/projects.md)
dotagent init . --name "Mein Projekt"
```

Das erstellt `.agent/` mit `agent.md`, `status.md`, `log.md`, `specification.md`, `plans/` und Symlinks auf die globalen `rules.md` / `functional.md`.

> **Auch hier gilt:** Bestehende Dateien und Symlinks werden nicht angetastet.

### 5. Loslegen

```bash
# Verfügbare Tools anzeigen
dotagent tools

# Projektstatus
dotagent status

# Projektübersicht
dotagent projects
```

---

## CLI-Referenz

### Infrastruktur

| Befehl | Beschreibung |
|---|---|
| `dotagent init` | Globalen `~/.agent/`-Ordner anlegen |
| `dotagent init .` | Projektlokalen `.agent/`-Ordner anlegen |
| `dotagent init . --name "Name"` | Mit Projektname für `projects.md` |
| `dotagent setup --check` | Credential-Status prüfen |
| `dotagent setup` | Interaktiver Setup-Wizard |
| `dotagent setup <provider>` | Einzelnes Credential einrichten |
| `dotagent setup --write-zshrc` | Export-Befehle direkt in `~/.zshrc` schreiben |
| `dotagent tools` | Alle verfügbaren Tools auflisten |
| `dotagent tools --json` | JSON-Output (maschinell) |
| `dotagent tools --agent` | Markdown für Agent-System-Prompt |
| `dotagent projects` | Projektübersicht aus `~/.agent/projects.md` |
| `dotagent status` | Status des aktuellen Projekts |

### Knowledgebase (`dotagent kb`)

Semantische Suche über E-Books und Dokumente (benötigt `pip install "dot-agent[kb]"`).

| Befehl | Beschreibung |
|---|---|
| `dotagent kb init <pfad> --name <name>` | Neue Knowledgebase aus Ordner erstellen |
| `dotagent kb search "query" --name <name>` | Semantisch suchen |
| `dotagent kb search "query" --name <name> --json` | Suchergebnisse als JSON |
| `dotagent kb ask "Frage" --name <name>` | RAG-basierte Antwort |
| `dotagent kb kbs` | Alle Knowledgebases auflisten |

### Vision-Tool (`dotagent vision`)

Bilderkennung für AI-Agents – Screenshots, Diagramme, Fotos beschreiben (benötigt `pip install "dot-agent[vision]"`).

| Befehl | Beschreibung |
|---|---|
| `dotagent vision describe bild.png` | Bild beschreiben |
| `dotagent vision describe bild.png --prompt "Was zeigt dieser Fehler?"` | Gezielte Analyse |
| `dotagent vision describe https://example.com/img.png` | URL-Support |
| `dotagent vision describe bild.png --json` | JSON-Output |
| `dotagent vision describe bild.png --model gpt-4.1` | Anderes Modell |

### Bildgenerierung (`dotagent beuys`)

KI-Bildgenerierung via OpenAI gpt-image-1-mini (benötigt `pip install "dot-agent[beuys]"`).

| Befehl | Beschreibung |
|---|---|
| `dotagent beuys generate "Prompt"` | Bild generieren und öffnen |
| `dotagent beuys generate "Prompt" --no-open` | Ohne automatisches Öffnen |
| `dotagent beuys generate "Prompt" -o ./images` | Ausgabeverzeichnis festlegen |

---

## Überschreibschutz

`dotagent init` ist **idempotent und sicher** für bestehende Setups:

- **Dateien:** Werden nur erstellt, wenn sie noch nicht existieren (`_write_if_missing`)
- **Symlinks:** Werden nur erstellt, wenn weder Datei noch Symlink vorhanden
- **Verzeichnisse:** Werden nur erstellt, wenn sie noch nicht existieren
- **Output:** Zeigt für jede Datei an, ob sie erstellt oder übersprungen wurde

```
✅ Globales Init (~/.agent/)

  Übersprungen (existiert bereits):
    • /Users/.../.agent/rules.md
    • /Users/.../.agent/functional.md
    • /Users/.../.agent/projects.md
    • /Users/.../.agent/config.toml
```

Das bedeutet: `dotagent init` kann jederzeit erneut ausgeführt werden – bestehende Konfigurationen, Projekte und Agent-Anweisungen bleiben unverändert.

---

## Architektur

```
src/dotagent/
├── cli.py              # Typer CLI: Hauptgruppe mit Subcommand-Gruppen
├── config.py           # Globale Konfiguration
├── core/
│   ├── init.py         # .agent-Ordner anlegen (global + projektlokal)
│   ├── tools.py        # Tool-Registry: Discovery, Dokumentation
│   ├── config_toml.py  # TOML-basierte Konfiguration
│   └── credentials.py  # API-Key-Management
├── kb/                 # Knowledgebase (Subcommand-Gruppe)
│   ├── cli.py
│   └── core/
├── beuys/              # Bildgenerierung (Subcommand-Gruppe)
│   ├── cli.py
│   └── core/
└── templates/          # Templates für agent.md, rules.md, functional.md, status.md
```

## .agent-Ordner-Struktur

### Global (`~/.agent/`)

| Datei | Funktion |
|---|---|
| `rules.md` | Coding-Standards, Architektur, Workflow |
| `functional.md` | FP-Regeln für Code-Generierung |
| `projects.md` | Zentrale Projektübersicht |
| `config.toml` | Konfiguration und Credential-Specs |
| `tools.d/` | Externe Tool-Definitionen (`.toml`-Dateien) |

### Projektlokal (`<projekt>/.agent/`)

| Datei | Funktion |
|---|---|
| `agent.md` | Projektspezifische Agent-Anweisungen |
| `rules.md` | Symlink → `~/.agent/rules.md` |
| `functional.md` | Symlink → `~/.agent/functional.md` |
| `status.md` | Projektstatus (maschinenlesbar) |
| `log.md` | Änderungsprotokoll |
| `specification.md` | Projektspezifikation |
| `plans/` | Pläne und Feature-Dokumente |

## Credentials

Unterstützte Provider:

| Provider | Env-Vars | Benötigt für |
|---|---|---|
| OpenAI | `OPENAI_API_KEY` | kb, beuys |
| Atlassian | `JIRA_USER_EMAIL`, `JIRA_API_TOKEN` | Jira/Confluence |
| GitLab | `GITLAB_TOKEN`, `GITLAB_URL` | GitLab API |

### Externe Tools registrieren

Eigene Tools können als `.toml`-Dateien in `~/.agent/tools.d/` registriert werden:

```toml
# ~/.agent/tools.d/mein-tool.toml
[tool]
name = "mein-tool"
description = "Beschreibung"
commands = ["mein-tool run", "mein-tool status"]
```

Diese erscheinen dann in `dotagent tools` und `dotagent tools --agent`.

## Entwicklung

```bash
# Installation für Entwicklung
pip install -e ".[dev]"

# Tests ausführen
pytest

# Mit Coverage
pytest --cov=dotagent

# Einzelne Test-Datei
pytest tests/test_init.py -v
```

## Voraussetzungen

- Python ≥ 3.11
- Für kb: OpenAI API Key, faiss-cpu, pymupdf
- Für beuys: OpenAI API Key

## Lizenz

MIT
