Icking Pipeline Handoff — Technische API-Doku für Florian + Email an Christoph & Nicole

Session-Prompt — Icking Pipeline Handoff

Aufgabe in dieser Session:

1. Technische API-Dokumentation für Florian schreiben — wie ruft er die Pipeline auf, was kommt zurück, wie geht er mit den aktuellen Limitierungen um.
2. Stakeholder-Email an Christoph und Nicole mit den Eval-Ergebnissen — Marvin diktiert den Inhalt.

Kontext — was bereits steht

Pipeline-Stand

Production-Service https://inference.agenticventures.de/search läuft auf:

• ECS Cluster inference-service-prod im AWS-Account av-production (425924867359), Region eu-central-1
• Task-Definition Revision 9 mit Image :phase4-final-retry
• Image enthält den heute deployed RetryRerankProvider der bei Bedrock-Throttle synchron wartet statt 500 zu liefern
• Service ist gesund: /healthz 200, /readyz mit allen Checks grün

Auswertung vom 18.05.2026 (51 Architekten-Queries)

Metrik	Wert
R@1 (Top-1-Treffer)	38/51 = 74,5 %
R@3	44/51 = 86,3 %
R@5	49/51 = 96,1 %
R@10	49/51 = 96,1 %
HTTP-Fehler	0 / 51 (vorher 6 = 12 %)
Latenz Median	10,1 s (durch AWS-Quota-Throttle, nicht durch Pipeline-Logik)

PDF mit AV-Design fertig + in S3 hochgeladen:

• s3://av-icking-eval-data/reports/2026-05-18/icking-pipeline-auswertung.pdf (243 KB, 7 Seiten)
• Quell-HTML + Charts daneben unter demselben Prefix

AWS-Quota-Status

Quota	Code	Aktuell	Ziel	Status
Cohere Rerank 3.5 RPM	L-11512E58	3	250	Support Case offen (heute eingereicht, “General guidance” + Web-Response)
Amazon Rerank 1.0 RPM	L-AAB0080F	2	200	gleicher Case
Haiku 4.5 Cross-region RPM	L-CCA5DF70	10	10.000	PENDING via service-quotas-API (gestern Abend)
Haiku 4.5 Global Cross-region RPM	L-E5084BBA	10	10.000	PENDING

Solange Rerank-Quota nicht erhöht ist: Service kann sequentiell maximal ~3 Anfragen pro Minute sicher beantworten. Bei mehr wartet er aktiv (Retry-Wrapper), aber Latenz spürbar.

Account-Setup (neu)

Sub-Account av-icking mit Account-ID 376761748837 in der Org o-p197skdqva. Identity-Center-Zugriff via https://d-996749743e.awsapps.com/start mit AdministratorAccess-Permission-Set.

S3-Bucket av-icking-eval-data (eu-central-1) enthält:

• eval/eval_set_long_florian.jsonl — 51 Architekten-Queries (Generator-Output)
• eval/eval_set_original.jsonl — Florians ursprüngliche Stichwort-Queries
• reports/2026-05-18/ — PDF-Report, Charts, Raw-Results, HTML-Quelle

Wichtige API-Details

Endpoint: POST https://inference.agenticventures.de/search

Auth: Bearer-Token im Authorization-Header.

• Secret: inference-service-prod/api-key in Secrets Manager (Account av-production, eu-central-1)
• Aktueller Key: api_key_v1 → 08c999b4d962b7fd5b2c97e73a52473dee76c97de6b687ed1ed1d0dc6077b3fc
• Rotation-Pattern (api_key_v1 + api_key_v2 parallel) ist im Code vorgesehen, aktuell nur v1 belegt.

Request-Schema (app/routers/search.py):

{
  "query": "string, max 512 Zeichen, Whitelist: [\\w \\t\\-äöüÄÖÜß.,/()²³°+%:]",
  "top_k": 3,                  // optional, Default 3, max 100
  "candidate_pool": 100        // optional, Default 100, max 200
}

Response-Schema:

{
  "request_id": "uuid",
  "query": "echo der Anfrage",
  "results": [
    {
      "id": 102733,
      "name": "L210110020035",
      "kurztext": "Oberlage Bauder KARAT:\r\nLieferung und ...",
      "einheit": "m²",
      "wgr": "210110",
      "tgk": "41",
      "score": 0.803,            // Hybrid-Fusion
      "rerank_score": 0.861,     // Cohere Rerank 3.5
      "semantic_score": 0.792,
      "keyword_score": 1.0,
      "measurement_score": 0.0
    }
  ]
}

HTTP-Codes:

• 200 — Erfolg
• 401 — Auth fehlt oder ungültig
• 422 — Request-Validierung (Query leer, zu lang, ungültige Zeichen)
• 500 — generischer Fehler (sollte aktuell nicht mehr passieren)
• 503 — Upstream-Quota erschöpft, mit Retry-After: 30-Header. Client sollte nach der angegebenen Wartezeit retryen.

Aufgabe 1 — Technische API-Dokumentation für Florian

Was Florian braucht

Florian ist Bauleiter/Architekt, nicht Software-Entwickler, aber technisch firm genug für eine ordentliche API-Doku. Er will wissen:

• Wie schickt er eine Anfrage (curl + Python — er kann Python)
• Was kommt zurück, was bedeutet was
• Was tut er bei Fehlern
• Wie umgeht er die aktuelle Quota-Limitierung (sequentiell schicken, Retry-After respektieren)
• Wo bekommt er einen API-Key wenn der aktuelle ungültig wird

Format

HTML/PDF im selben AV-Design wie der Eval-Report, damit der Stil konsistent ist. Vorlage:

• /tmp/charts_v2/report.html ist die HTML-Quelle des Eval-Reports
• Brand-Assets: /Users/marvinkuehlmann/source/agentic-ventures/assets/firma/brand-assets/
  • Inter-Regular/Medium/SemiBold.ttf
  • wortmarke-agentic-ink-bone.png
• Render via Playwright Chromium (/tmp/charts_v2/render_pdf.py als Vorlage)

Brand-Farben:

• Primary: #2D4A3E (AV Deep Green)
• Background: #FAFAF7 (cream)
• Ink: #0A0A0A
• Muted: #6B7280
• Border: #E5E7EB
• Warm/Akzent für „Achtung”: #D97757

Aufbau-Vorschlag (~6-8 Seiten):

1. Cover (Wortmarke + Titel „Pipeline API — Technische Dokumentation”)
2. Übersicht: Was die Pipeline tut, Endpoint, Auth-Prinzip
3. Erste Anfrage (mit Beispiel-Curl + Python, Antwort gezeigt)
4. Request-Schema (alle Felder erklärt)
5. Response-Schema (alle Felder erklärt, mit was die Score-Werte bedeuten)
6. Fehlerbehandlung (HTTP-Codes + was tun)
7. Rate-Limit + Retry-Empfehlungen (aktuell 3 RPM, nach Quota-Erhöhung viel mehr)
8. Beispiel-Workflow (10 Queries hintereinander mit korrektem Pausieren)
9. API-Key (wer Marvin anschreibt für Rotation, Sicherheits-Hinweise)
10. Roadmap/Status (was kommt als nächstes — z.B. Phase-5 Catalog-Anreicherung für bessere R@1)

Wichtig — Tonfall:

• Sachlich, technisch, keine Marketing-Sprüche
• Code-Snippets in Mono-Schrift mit AV-Brand-konformer Farbgebung
• Konkrete Werte, keine Beispiel-Platzhalter wie <API_KEY> wo möglich (Marvin wird’s an Florian schicken, Wert kann konkret rein — der Key ist nur für Florian gedacht)

Output:

• /tmp/api-doku/florian-api-doku.pdf
• Plus Upload nach s3://av-icking-eval-data/reports/2026-05-18/florian-api-doku.pdf

Aufgabe 2 — Email an Christoph und Nicole

Nach der API-Doku, nicht parallel. Marvin diktiert den Email-Inhalt während du arbeitest oder danach.

Was vermutlich rein soll

• Eval-Ergebnis kurz zusammenfassen (R@1 74,5 %, R@5 96,1 %, 0 Fehler)
• PDF-Report anhängen (/tmp/charts_v2/icking-pipeline-auswertung.pdf)
• Was als nächstes ansteht (AWS-Quota-Erhöhung kommt, Phase-5 läuft)
• Florian hat ab jetzt eine vollständige API-Doku (verlinken oder anhängen)
• Was Marvin von Christoph + Nicole braucht (offen — Marvin diktiert)

Wichtige Regel für externen Schriftverkehr

Style-Profil: style-profile-marvin vor dem Draft lesen.

• Keine Em-Dashes (—), keine En-Dashes (–) — Komma/Punkt/Doppelpunkt/Klammern verwenden
• Ich-Form statt „wir”
• Konkrete Verben, kurze Sätze
• Keine Marketing-Floskeln, kein „aus meiner Sicht”
• Begrüßungs-/Schluss-Formel passend zum Vertrautheits-Grad (Marvin sagt’s wenn er den Empfänger erstmal mit „Hallo” oder „Sehr geehrte” anschreibt)

Email-Account: vermutlich hello@marvinkuehlmann.com (Business). Marvin sagt’s wenn nicht.

Skill: agentic-ventures:email-schreiben — verwenden statt von Null.

Wichtig: Email als Draft anlegen, NICHT sofort senden. Marvin checkt vor dem Send.

Wer sind Christoph und Nicole

Aktuell ist mir nicht klar — Marvin gibt die Kontext-Info beim Diktat. Wahrscheinlich Stakeholder bei Icking oder Vertretung von Florian’s Seite. Vor dem Draft kurz nachfragen wenn unklar.

Pflichtlektüre vor Start

1. Diese Datei
2. /tmp/charts_v2/report.html — HTML-Quelle des Eval-Reports (Vorlage für Design-Sprache)
3. /Users/marvinkuehlmann/source/agentic-ventures/CLAUDE.md — Vault-Regeln (insbes. Rule 15 zu Sprache + Ton, Rule 22 zu Kunden-Namen)
4. /Users/marvinkuehlmann/source/agentic-ventures/intern/capabilities/skills/email-schreiben/style-profile-marvin.md — vor jedem Email-Draft

Erwarteter Ablauf

1. Diesen Prompt lesen + bestätigen dass Kontext klar ist
2. API-Doku bauen (HTML + Render zu PDF) — Marvin checkt Zwischenstand
3. Nach Marvins OK: Upload nach S3 av-icking
4. Marvin diktiert Email-Inhalt
5. Email-Draft via email-schreiben-Skill mit PDF-Anhang
6. Marvin reviewed Draft, sendet selbst

Dateipfade — wichtige Übersicht

Was	Wo
Eval-PDF (Vorlage)	/tmp/charts_v2/icking-pipeline-auswertung.pdf
Eval-HTML-Quelle	/tmp/charts_v2/report.html
Eval-Charts v2	/tmp/charts_v2/{1_recall,2_rank,3_latency}.png
Raw-Eval-Results	/tmp/florian_long_results.jsonl (51 Cases mit Rank/Latency)
Long-Eval-Set	/tmp/florian_long.jsonl
Brand-Assets	~/source/agentic-ventures/assets/firma/brand-assets/
Service-Repo	~/source/a-icking/inference-service/
Search-Router-Code	~/source/a-icking/inference-service/app/routers/search.py
AWS S3 av-icking	s3://av-icking-eval-data/ (assume-role von mgmt Profil)
AWS prod	--profile av-production --region eu-central-1

Vault-Cross-Refs

• Projekt: [[../../projekte/icking-ai-rebuild/_index]]
• Phase-5-Plan (Vorgänger): [[../2026-05-17-icking-phase-2/next-session-prompt-phase5-llm]]
• Phase-4-Bilanz: ~/source/a-icking/docs/decisions/2026-05-17-phase-4-shipped.md
• Marvin-Email-Style: [[../../capabilities/skills/email-schreiben/style-profile-marvin]]

---

Mantra für diese Session: Florian + Christoph + Nicole sind Endkunde, kein interner Stakeholder. Alles was rausgeht muss Marvin-Style-konform sein (siehe Rule 15) und NDA-konform (Rule 22 — keine anderen Kunden-Namen erwähnen).