meander-agent 0.1.0__py3-none-any.whl

meander_agent/__init__.py

@@ -0,0 +1,47 @@
+# src/meander_agent/__init__.py
+"""meander-agent: kundenseitiges SDK für die meander.plan-Sende-Seite.
+
+Öffentliche Fläche ist genau das hier Re-Exportierte. Drei Schichten:
+- Transport: ``init_meander(endpoint, source_key)`` -> ``MeanderClient`` (OTel +
+  OTLP-Export auf den meander-Ingress; der einzige nötige Aufruf ohne eigenes OTel).
+- Emitter: ``attach_plan`` / ``validate_plan_shape`` (SDK-neutrale FORM-Prüfung +
+  Attribut-Anhang; importiert meander NICHT).
+- Kern + dünne SDK-Bindings (``meander_agent.claude`` / ``meander_agent.openai``,
+  Extras ``[claude]`` / ``[openai]``) folgen in Block B/C.
+"""
+from meander_agent.core import (
+    Run,
+    RunResult,
+    build_output_schema,
+    build_prompt_fragment,
+    meander_run,
+    meander_run_decorator,
+)
+from meander_agent.emitter import (
+    ORIGIN_KINDS,
+    PLAN_ATTRIBUTE_KEY,
+    PLAN_VERSION,
+    AttachResult,
+    ShapeError,
+    attach_plan,
+    validate_plan_shape,
+)
+from meander_agent.transport import MeanderClient, init_meander
+
+__all__ = [
+    "ORIGIN_KINDS",
+    "PLAN_ATTRIBUTE_KEY",
+    "PLAN_VERSION",
+    "AttachResult",
+    "MeanderClient",
+    "Run",
+    "RunResult",
+    "ShapeError",
+    "attach_plan",
+    "build_output_schema",
+    "build_prompt_fragment",
+    "init_meander",
+    "meander_run",
+    "meander_run_decorator",
+    "validate_plan_shape",
+]

meander_agent/claude.py

@@ -0,0 +1,101 @@
+# src/meander_agent/claude.py
+"""Dünnes Claude-Agent-SDK-Binding auf den Kern (``meander_run`` / ``finalize``).
+
+SDK-spezifisch ist hier NUR: der ``query()``-Aufruf mit nativer strukturierter
+JSON-Ausgabe (``output_format`` = ``run.output_schema``), das Einsammeln der
+terminalen ``ResultMessage`` (Run-Ende) und die Übersetzung der Claude-Semantik
+(``subtype``/``is_error``) auf den neutralen ``error_state``. Baustein, Parsen,
+Formprüfung, Fehler-Sperren, Anhängen und ``RunResult`` kommen ALLE aus dem Kern.
+
+Kein meander-Import. Der Root-Span wird vom Kern-Kontextmanager gehalten; das
+Binding ruft ``run.finalize(output, error_state)``, solange er offen ist.
+"""
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+from meander_agent.core import RunResult, meander_run
+
+# SDK-Subtypes: die native strukturierte Ausgabe meldet bei Erfolg "success",
+# bei erschöpften Retries "error_max_structured_output_retries" (Beispiel).
+_SUBTYPE_SUCCESS = "success"
+_SUBTYPE_MAX_STRUCTURED_RETRIES = "error_max_structured_output_retries"
+
+
+def _claude_error_state(
+    subtype: str | None, is_error: bool, errors: list[str] | None
+) -> dict | None:
+    """Claude-Terminal-Semantik -> neutraler error_state.
+
+    Ein Fehler-Subtype (alles außer ``None``/``"success"``) ODER ``is_error``
+    ergibt einen error_state (Sperre im Kern). Erfolg -> ``None``.
+    """
+    if is_error or (subtype is not None and subtype != _SUBTYPE_SUCCESS):
+        return {"subtype": subtype, "is_error": is_error, "errors": list(errors or [])}
+    return None
+
+
+def _claude_output(structured_output: Any, result_text: str | None) -> Any:
+    """Bevorzugt die strukturierte Ausgabe (dict); sonst der reine result-Text
+    (den der Kern per json.loads prüft). Kein Prosa-Extrahieren."""
+    return structured_output if isinstance(structured_output, dict) else result_text
+
+
+async def run_with_plan_async(
+    task: str,
+    *,
+    vocabulary: Any,
+    tracer: Any,
+    root_span_name: str = "agent.run",
+    options_extra: dict[str, Any] | None = None,
+) -> RunResult:
+    """Fährt query() mit output_format und finalisiert über den Kern.
+
+    Öffnet den Run-Root-Span (Kern), fährt den ``query()``-Async-Iterator selbst
+    durch, sammelt die terminale ``ResultMessage`` und ruft ``run.finalize`` —
+    solange der Span offen ist. Fehler werden vom Kern laut geloggt.
+    """
+    from claude_agent_sdk import ClaudeAgentOptions, ResultMessage, query
+
+    with meander_run(vocabulary=vocabulary, tracer=tracer, root_span_name=root_span_name) as run:
+        prompt = f"{task.strip()}\n\n{run.prompt_fragment}"
+        opts_kwargs: dict[str, Any] = {
+            "output_format": {"type": "json_schema", "schema": run.output_schema}
+        }
+        if options_extra:
+            opts_kwargs.update(options_extra)
+        options = ClaudeAgentOptions(**opts_kwargs)
+
+        terminal: Any = None
+        async for message in query(prompt=prompt, options=options):
+            if isinstance(message, ResultMessage):
+                terminal = message  # die terminale Nachricht ist verlässlich
+        if terminal is None:
+            return run.finalize(None, error_state={"errors": ["no terminal ResultMessage"]})
+
+        error_state = _claude_error_state(
+            terminal.subtype, getattr(terminal, "is_error", False), terminal.errors
+        )
+        output = _claude_output(terminal.structured_output, terminal.result)
+        return run.finalize(output, error_state)
+
+
+def run_with_plan(
+    task: str,
+    *,
+    vocabulary: Any,
+    tracer: Any,
+    root_span_name: str = "agent.run",
+    options_extra: dict[str, Any] | None = None,
+) -> RunResult:
+    """Synchroner Wrapper um ``run_with_plan_async`` (deterministische Nutzung)."""
+    return asyncio.run(
+        run_with_plan_async(
+            task,
+            vocabulary=vocabulary,
+            tracer=tracer,
+            root_span_name=root_span_name,
+            options_extra=options_extra,
+        )
+    )

meander_agent/core.py

@@ -0,0 +1,379 @@
+# src/meander_agent/core.py
+"""SDK-neutraler Adapter-Kern: Kontextmanager ``meander_run`` + ``finalize``.
+
+Der Kern öffnet den Run-Root-Span und liefert ausschließlich SDK-neutrale
+Primitive:
+- ``run.prompt_fragment`` — parametrisierter Baustein (Format + erlaubtes
+  Vokabular), den das Binding dem SDK übergibt;
+- ``run.output_schema`` — JSON-Schema der strukturierten Ausgabe (nur deklarierte
+  Namen), für Claudes ``output_format`` bzw. als Grundlage des OpenAI-Modells;
+- ``run.finalize(output, error_state)`` — Parsen -> Formprüfung über den Emitter
+  -> Fehler-Sperren -> Anhängen -> ``RunResult``.
+
+Der Kern übergibt NIE selbst Prompts ans SDK und liest NIE SDK-Resultate: wo der
+Baustein hingehört, wie strukturierte Ausgabe zurückkommt und wie Error/Abbruch
+aussieht, ist Binding-Sache. Das Binding sammelt beides ein und ruft
+``finalize(...)``. Exception durch den ``with``-Block ODER ``error_state != None``
+-> KEIN Attach. Der Kern bleibt SDK- und pydantic-frei; einziger Parse-Weg ist
+``json.loads`` auf der KOMPLETTEN Ausgabe (kein JSON-aus-Prosa-Extrahieren).
+"""
+from __future__ import annotations
+
+import functools
+import json
+import logging
+from contextlib import contextmanager
+from dataclasses import dataclass, field
+from typing import Any, Iterator
+
+from meander_agent.emitter import (
+    PLAN_VERSION,
+    ShapeError,
+    attach_plan,
+    validate_plan_shape,
+)
+
+logger = logging.getLogger("meander_agent.core")
+
+
+# --------------------------------------------------------------------------- #
+# Vokabular: nested Deklaration -> Prosa-Baustein + JSON-Schema
+# --------------------------------------------------------------------------- #
+def _normalize_vocabulary(vocabulary: Any) -> dict:
+    """Prüft die Vokabular-Form und gibt eine normalisierte Kopie zurück.
+
+    Erwartet::
+
+        {
+          "entities": {"<Entity>": {"identity": [...], "properties": [...]}},
+          "relations": {"<Relation>": {"from": "<Entity>", "to": "<Entity>"}},
+          "derivation_ids": [...],
+        }
+
+    Malformte Eingabe -> ValueError (laut, nie still).
+    """
+    if not isinstance(vocabulary, dict):
+        raise ValueError("vocabulary muss ein dict sein")
+    entities = vocabulary.get("entities", {})
+    relations = vocabulary.get("relations", {})
+    derivation_ids = vocabulary.get("derivation_ids", [])
+    if not isinstance(entities, dict):
+        raise ValueError("vocabulary['entities'] muss ein dict {Entity: {...}} sein")
+    if not isinstance(relations, dict):
+        raise ValueError("vocabulary['relations'] muss ein dict {Relation: {...}} sein")
+    if not isinstance(derivation_ids, list) or not all(isinstance(d, str) for d in derivation_ids):
+        raise ValueError("vocabulary['derivation_ids'] muss eine Liste von Strings sein")
+
+    norm_entities: dict[str, dict] = {}
+    for name, spec in entities.items():
+        if not isinstance(spec, dict):
+            raise ValueError(f"entities[{name!r}] muss ein dict {{identity, properties}} sein")
+        identity = spec.get("identity", [])
+        properties = spec.get("properties", [])
+        if not isinstance(identity, list) or not all(isinstance(f, str) for f in identity):
+            raise ValueError(f"entities[{name!r}]['identity'] muss eine Liste von Strings sein")
+        if not isinstance(properties, list) or not all(isinstance(p, str) for p in properties):
+            raise ValueError(f"entities[{name!r}]['properties'] muss eine Liste von Strings sein")
+        norm_entities[name] = {"identity": list(identity), "properties": list(properties)}
+
+    norm_relations: dict[str, dict] = {}
+    for name, spec in relations.items():
+        if not isinstance(spec, dict) or "from" not in spec or "to" not in spec:
+            raise ValueError(f"relations[{name!r}] muss ein dict {{from, to}} sein")
+        frm, to = spec["from"], spec["to"]
+        if frm not in norm_entities or to not in norm_entities:
+            raise ValueError(
+                f"relations[{name!r}] verweist auf nicht deklarierte Endpunkt-Entity "
+                f"(from={frm!r}, to={to!r})"
+            )
+        norm_relations[name] = {"from": frm, "to": to}
+
+    return {"entities": norm_entities, "relations": norm_relations,
+            "derivation_ids": list(derivation_ids)}
+
+
+# Format-Baustein (Prompt-Hygiene: nur Platzhalter, keine echten Fakten-Werte).
+_PLAN_FORMAT_PROMPT = """\
+Liefere als FINALE strukturierte Ausgabe GENAU EIN JSON-Objekt im Plan-Format
+(plan_version 1). Das Objekt hat diese Felder:
+
+- "plan_version": muss exakt die Zahl 1 sein.
+- "facts": Liste behaupteter Welt-Fakten. Jeder Fakt trägt SEINE Herkunft:
+    {"entity": "<entity>", "identity": {"<id_field>": "PLACEHOLDER_ID"},
+     "property": "<property>", "value": <typkonformer Wert>,
+     "origin": {"kind": "tool"|"api"|"human"|"agent", "ref": "<optional>"}}
+  Herkunft je Fakt: Tool-Ergebnisse origin.kind "tool", eigene Einschätzungen
+  origin.kind "agent". Fehlt "origin", gilt "agent".
+- "relations": Liste behaupteter Beziehungen (optional):
+    {"relation": "<relation>",
+     "from": {"entity": "<entity>", "identity": {"<id_field>": "PLACEHOLDER_ID"}},
+     "to": {"entity": "<entity>", "identity": {"<id_field>": "PLACEHOLDER_ID"}},
+     "origin": {"kind": "tool"|"api"|"human"|"agent"}}
+- "question": GENAU EINE Frage an eine bestehende Derivation:
+    {"derivation_id": "<derivation_id>",
+     "subject": {"entity": "<entity>", "identity": {"<id_field>": "PLACEHOLDER_ID"}}}
+- "rule_proposals": optionale Liste von Regel-Vorschlägen:
+    {"id": "<proposal_id>", "head": {...}, "when": [...]}
+
+Triff KEINE Entscheidung. Behaupte nur Fakten mit ihrer Herkunft und stelle die
+eine Frage. Die PLACEHOLDER_ID- und <...>-Marker stehen für echte Werte aus
+deinen Tool-Aufrufen, NICHT wörtlich zu übernehmen. Verwende AUSSCHLIESSLICH das
+unten deklarierte Vokabular: je Entity nur ihre identity-Felder und Properties,
+je Relation nur ihre deklarierten Endpunkt-Entities."""
+
+
+def build_prompt_fragment(vocabulary: Any) -> str:
+    """Baustein: Format + das deklarierte Vokabular (task-frei).
+
+    Das Binding hängt die konkrete Aufgabe davor/als Nutzereingabe an. Nennt je
+    Entity ihre identity-Felder und Properties, je Relation ihre Endpunkte, sowie
+    die erlaubten Derivation-IDs — nur diese Namen sind zulässig.
+    """
+    v = _normalize_vocabulary(vocabulary)
+    lines = ["", "Erlaubtes Vokabular (nur diese Namen verwenden):", "Entities:"]
+    for name, spec in v["entities"].items():
+        ids = ", ".join(spec["identity"]) or "(keine)"
+        props = ", ".join(spec["properties"]) or "(keine)"
+        lines.append(f"- {name}: identity-Felder {{{ids}}}; properties {{{props}}}")
+    lines.append("Relations:")
+    if v["relations"]:
+        for name, spec in v["relations"].items():
+            lines.append(f"- {name}: from {spec['from']} to {spec['to']}")
+    else:
+        lines.append("- (keine)")
+    lines.append("Erlaubte Derivation-IDs: " + (", ".join(v["derivation_ids"]) or "(keine)"))
+    return f"{_PLAN_FORMAT_PROMPT}\n" + "\n".join(lines) + "\n"
+
+
+_ORIGIN_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "kind": {"type": "string", "enum": ["tool", "api", "human", "agent"]},
+        "ref": {"type": "string"},
+    },
+    "required": ["kind"],
+    "additionalProperties": False,
+}
+
+
+def _identity_schema(fields: list[str]) -> dict:
+    # Geschlossenes Objekt: identity-Schlüssel NUR aus den deklarierten Feldern
+    # (properties + additionalProperties:False; breit von Structured-Output unterstützt).
+    return {
+        "type": "object",
+        "properties": {f: {"type": "string"} for f in fields},
+        "additionalProperties": False,
+    }
+
+
+def _endpoint_schema(entity_names: list[str], id_fields: list[str]) -> dict:
+    return {
+        "type": "object",
+        "properties": {
+            "entity": {"type": "string", "enum": entity_names},
+            "identity": _identity_schema(id_fields),
+        },
+        "required": ["entity", "identity"],
+        "additionalProperties": False,
+    }
+
+
+def build_output_schema(vocabulary: Any) -> dict:
+    """JSON-Schema der strukturierten Ausgabe, an das Vokabular gebunden.
+
+    Erzwingt „nur deklarierte Namen" über Enums (entity/property/relation/
+    derivation_id) und geschlossene identity-Objekte (Schlüssel nur aus den
+    deklarierten id-Feldern). Die per-Relation-Paarung (welche Entity von/nach
+    welcher) und per-Entity-Property-Zuordnung stehen im ``prompt_fragment`` und
+    werden serverseitig autoritativ geprüft.
+    """
+    v = _normalize_vocabulary(vocabulary)
+    entity_names = list(v["entities"])
+    relation_names = list(v["relations"])
+    all_properties = sorted({p for e in v["entities"].values() for p in e["properties"]})
+    all_id_fields = sorted({f for e in v["entities"].values() for f in e["identity"]})
+
+    return {
+        "type": "object",
+        "properties": {
+            "plan_version": {"const": PLAN_VERSION},
+            "facts": {
+                "type": "array",
+                "items": {
+                    "type": "object",
+                    "properties": {
+                        "entity": {"type": "string", "enum": entity_names},
+                        "identity": _identity_schema(all_id_fields),
+                        "property": {"type": "string", "enum": all_properties},
+                        "value": {},
+                        "origin": _ORIGIN_SCHEMA,
+                    },
+                    "required": ["entity", "identity", "property", "value"],
+                    "additionalProperties": False,
+                },
+            },
+            "relations": {
+                "type": "array",
+                "items": {
+                    "type": "object",
+                    "properties": {
+                        "relation": {"type": "string", "enum": relation_names},
+                        "from": _endpoint_schema(entity_names, all_id_fields),
+                        "to": _endpoint_schema(entity_names, all_id_fields),
+                        "origin": _ORIGIN_SCHEMA,
+                    },
+                    "required": ["relation", "from", "to"],
+                    "additionalProperties": False,
+                },
+            },
+            "question": {
+                "type": "object",
+                "properties": {
+                    "derivation_id": {"type": "string", "enum": list(v["derivation_ids"])},
+                    "subject": _endpoint_schema(entity_names, all_id_fields),
+                },
+                "required": ["derivation_id", "subject"],
+                "additionalProperties": False,
+            },
+            "rule_proposals": {
+                "type": "array",
+                "items": {
+                    "type": "object",
+                    "properties": {
+                        "id": {"type": "string"},
+                        "head": {"type": "object"},
+                        "when": {"type": "array"},
+                    },
+                    "required": ["id", "head", "when"],
+                    "additionalProperties": False,
+                },
+            },
+        },
+        "required": ["plan_version", "question"],
+        "additionalProperties": False,
+    }
+
+
+# --------------------------------------------------------------------------- #
+# RunResult + Kontextmanager + finalize
+# --------------------------------------------------------------------------- #
+@dataclass
+class RunResult:
+    """Ergebnis eines Adapter-Laufs (auch bei Fehlern voll befüllt)."""
+
+    plan: dict | None = None
+    attached: bool = False
+    shape_errors: list[ShapeError] = field(default_factory=list)
+    error_state: Any = None
+
+
+class Run:
+    """Vom ``meander_run``-Kontextmanager geliefertes Handle (nur SDK-neutrale Primitive)."""
+
+    def __init__(self, span: Any, vocabulary: Any) -> None:
+        self._span = span
+        self._vocabulary = vocabulary
+        self._prompt_fragment: str | None = None
+        self._output_schema: dict | None = None
+
+    @property
+    def prompt_fragment(self) -> str:
+        if self._prompt_fragment is None:
+            self._prompt_fragment = build_prompt_fragment(self._vocabulary)
+        return self._prompt_fragment
+
+    @property
+    def output_schema(self) -> dict:
+        if self._output_schema is None:
+            self._output_schema = build_output_schema(self._vocabulary)
+        return self._output_schema
+
+    def finalize(self, output: Any, error_state: Any) -> RunResult:
+        """Parsen -> Formprüfung -> Fehler-Sperren -> Anhängen -> RunResult.
+
+        - ``error_state is not None`` -> KEIN Attach, lautes Log (auch bei
+          gültiger ``output``: ein Fehlerlauf ist kein Plan).
+        - ``output`` ist ein dict -> direkt nutzen; ist ein String -> ``json.loads``
+          auf den GANZEN String (kein Prosa-Extrahieren); sonst kein Plan.
+        - Formfehler / fehlende Ausgabe / nicht beschreibbarer Span -> KEIN Attach.
+        """
+        if error_state is not None:
+            logger.error(
+                "Modell-Lauf meldet einen Error-State (%r) — output verworfen, "
+                "KEIN meander.plan-Attribut", error_state,
+            )
+            return RunResult(plan=None, attached=False, error_state=error_state)
+
+        plan: dict | None = output if isinstance(output, dict) else None
+        if plan is None and isinstance(output, str):
+            try:
+                parsed = json.loads(output)
+            except (TypeError, ValueError):
+                parsed = None
+            if isinstance(parsed, dict):
+                plan = parsed
+
+        if plan is None:
+            logger.error(
+                "kein Plan in der Modell-Ausgabe (output=%r) — KEIN meander.plan-Attribut",
+                output,
+            )
+            return RunResult(plan=None, attached=False, error_state=error_state)
+
+        shape_errors = validate_plan_shape(plan)
+        if shape_errors:
+            logger.error(
+                "Plan aus der Modell-Ausgabe ist formfehlerhaft — KEIN Attribut. Fehler: %s",
+                [e.as_dict() for e in shape_errors],
+            )
+            return RunResult(plan=plan, attached=False, shape_errors=shape_errors,
+                             error_state=error_state)
+
+        attach = attach_plan(self._span, plan)
+        if not attach.ok:
+            # validate lief durch -> hier bleiben already_attached (Doppel-Anhang)
+            # oder span_not_recording (beendeter Span). Laut melden, nie still.
+            logger.error(
+                "attach_plan verweigert das Attribut: %s",
+                [e.as_dict() for e in attach.errors],
+            )
+            return RunResult(plan=plan, attached=False, shape_errors=attach.errors,
+                             error_state=error_state)
+
+        return RunResult(plan=plan, attached=True, error_state=error_state)
+
+
+@contextmanager
+def meander_run(
+    *,
+    vocabulary: Any,
+    tracer: Any,
+    root_span_name: str = "agent.run",
+) -> Iterator[Run]:
+    """Öffnet den Run-Root-Span und liefert ein SDK-neutrales ``Run``-Handle.
+
+    Der Span bleibt offen, solange ``finalize`` läuft, und schließt beim Verlassen.
+    Eine Exception durch den ``with``-Block wird am Span vermerkt und lässt KEIN
+    Attribut zurück (``finalize`` lief dann nicht erfolgreich durch).
+    """
+    with tracer.start_as_current_span(root_span_name) as span:
+        yield Run(span=span, vocabulary=vocabulary)
+
+
+def meander_run_decorator(
+    *,
+    vocabulary: Any,
+    tracer: Any,
+    root_span_name: str = "agent.run",
+):
+    """Dünner Zucker über ``meander_run``: dekoriert eine Funktion, die ``run``
+    als erstes Argument erhält. Kein Wrapping des Agent-Objekts."""
+    def deco(fn):
+        @functools.wraps(fn)
+        def wrapper(*args, **kwargs):
+            with meander_run(
+                vocabulary=vocabulary, tracer=tracer, root_span_name=root_span_name
+            ) as run:
+                return fn(run, *args, **kwargs)
+        return wrapper
+    return deco

meander_agent/emitter.py

@@ -0,0 +1,297 @@
+# src/meander_agent/emitter.py
+"""SDK-neutraler Plan-Emitter: reine FORM-Prüfung + Attribut-Anhang.
+
+Trägt das ``meander.plan``-Schema (Version 1) auf der SENDE-Seite. Prüft
+AUSSCHLIESSLICH die FORM eines Plans (Pflichtfelder, Typen, genau eine Frage,
+``origin.kind``-Vokabular, ``plan_version == 1``) und hängt einen formgültigen
+Plan als deterministisch serialisiertes Span-Attribut an einen echten OTel-Span.
+
+EINE Wahrheit für Semantik: der Client prüft NIE gegen die Ontologie. Welche
+Entities/Properties/Derivations existieren, weiß nur der Server (strikte
+serverseitige Validierung im meander-Receiver). Dieses Modul importiert meander
+NICHT und lädt keine Ontologie. Es hat auch KEINE Netzwerk-Logik — der Transport
+bleibt beim OTel-Export.
+
+Fehler werden nie still verschluckt: ``attach_plan`` gibt bei Formfehlern ein
+``AttachResult(ok=False, errors=[...])`` zurück und setzt KEIN Attribut (nie ein
+leeres/Platzhalter-Objekt). Ein Doppel-Anhang auf denselben Span scheitert laut,
+statt zu überschreiben.
+"""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from typing import Any
+from weakref import WeakSet
+
+# --- Client-Konstanten (KEIN Import aus meander) ---------------------------- #
+# Diese drei Konstanten spiegeln den Server-Kontrakt (meander.plans.semantics),
+# leben hier aber als EIGENE Client-Konstanten an genau EINER Stelle. Der Wert
+# von ``PLAN_VERSION`` wird gegen den Server-Wert abgeglichen (Gate-Test), aber
+# nicht importiert — der Client bleibt von meander entkoppelt.
+PLAN_ATTRIBUTE_KEY = "meander.plan"
+ORIGIN_KINDS: tuple[str, ...] = ("tool", "api", "human", "agent")
+PLAN_VERSION = 1
+
+# Abschließende Schlüsselmengen (unbekannte Schlüssel -> unknown_key). Spiegelt
+# die Server-Form (schema.py _TOP_KEYS etc.), damit ein Plan, den der Client
+# durchlässt, formseitig auch am Server passiert.
+_TOP_KEYS = {"plan_version", "facts", "relations", "question", "rule_proposals"}
+_FACT_KEYS = {"entity", "identity", "property", "value", "origin"}
+_RELATION_KEYS = {"relation", "from", "to", "origin"}
+_ENDPOINT_KEYS = {"entity", "identity"}
+_QUESTION_KEYS = {"derivation_id", "subject"}
+_ORIGIN_KEYS = {"kind", "ref"}
+_PROPOSAL_KEYS = {"id", "head", "when"}
+
+
+@dataclass(frozen=True)
+class ShapeError:
+    """Ein FORM-Fehler mit Feldpfad (z.B. ``facts[2].origin.kind``), Code, Message."""
+
+    path: str
+    code: str
+    message: str
+
+    def as_dict(self) -> dict[str, str]:
+        return {"path": self.path, "code": self.code, "message": self.message}
+
+
+@dataclass
+class AttachResult:
+    """Ergebnis von ``attach_plan``: ok, gesammelte Fehler, serialisierter Plan."""
+
+    ok: bool
+    errors: list[ShapeError] = field(default_factory=list)
+    serialized: str | None = None
+
+
+# Marker-Set: welche Spans schon ein Plan-Attribut per attach_plan tragen. Ein
+# WeakSet hält keine Spans künstlich am Leben; Doppel-Anhang wird so erkannt,
+# ohne den Span-Zustand zu lesen (manche Span-Impls geben Attribute nicht zurück).
+_ATTACHED: "WeakSet[object]" = WeakSet()
+
+
+class _Collector:
+    """Sammelt Fehler; bricht NIE beim ersten ab (alle Fehler auf einmal)."""
+
+    def __init__(self) -> None:
+        self.errors: list[ShapeError] = []
+
+    def add(self, path: str, code: str, message: str) -> None:
+        self.errors.append(ShapeError(path=path, code=code, message=message))
+
+    def unknown_keys(self, obj: dict[str, Any], allowed: set[str], path: str) -> None:
+        for key in obj:
+            if key not in allowed:
+                child = f"{path}.{key}" if path else str(key)
+                self.add(child, "unknown_key",
+                         f"unbekannter Schlüssel {key!r}; erlaubt sind {sorted(allowed)}")
+
+
+def validate_plan_shape(plan: Any) -> list[ShapeError]:
+    """Reine FORM-Prüfung eines Plans (Version 1). KEINE Ontologie-Prüfung.
+
+    Sammelt ALLE Fehler (kein early return) mit Feldpfad. Prüft:
+    ``plan_version`` exakt Integer 1; genau EINE ``question``; Pflichtfelder +
+    Typen je Fakt/Beziehung/Frage; ``origin.kind`` aus ORIGIN_KINDS (fehlendes
+    ``origin`` gilt als ``agent``, kein Fehler); ``rule_proposals`` Grobform;
+    unbekannte Schlüssel. ``facts``/``relations`` dürfen leer sein/fehlen.
+    """
+    col = _Collector()
+
+    if not isinstance(plan, dict):
+        col.add("", "invalid_shape",
+                f"Plan muss ein Objekt sein, ist {type(plan).__name__}")
+        return col.errors
+
+    col.unknown_keys(plan, _TOP_KEYS, "")
+
+    _check_version(plan.get("plan_version"), plan, col)
+    _check_facts(plan.get("facts"), plan, col)
+    _check_relations(plan.get("relations"), plan, col)
+    _check_question(plan, col)
+    _check_proposals(plan.get("rule_proposals"), plan, col)
+
+    return col.errors
+
+
+def _check_version(version: Any, plan: dict, col: _Collector) -> None:
+    # Exakt Integer 1. bool ist eine int-Unterklasse (True == 1) -> ausschließen.
+    # String "1" ist ein Fehler (gegen den Server-Wert PLAN_VERSION abgeglichen).
+    if "plan_version" not in plan:
+        col.add("plan_version", "invalid_plan_version",
+                f"plan_version muss exakt {PLAN_VERSION} sein, fehlt aber")
+        return
+    if not isinstance(version, int) or isinstance(version, bool) or version != PLAN_VERSION:
+        col.add("plan_version", "invalid_plan_version",
+                f"plan_version muss exakt {PLAN_VERSION} (Integer) sein, bekam {version!r}")
+
+
+def _check_origin(raw: Any, path: str, col: _Collector) -> None:
+    """Fehlendes ``origin`` gilt als {kind: agent} — KEIN Fehler."""
+    if raw is None:
+        return
+    if not isinstance(raw, dict):
+        col.add(path, "invalid_shape", "origin muss ein Objekt {kind, ref?} sein")
+        return
+    col.unknown_keys(raw, _ORIGIN_KEYS, path)
+    kind = raw.get("kind")
+    if kind not in ORIGIN_KINDS:
+        col.add(f"{path}.kind", "unknown_origin_kind",
+                f"origin.kind muss aus {list(ORIGIN_KINDS)} sein, bekam {kind!r}")
+    ref = raw.get("ref")
+    if ref is not None and not isinstance(ref, str):
+        col.add(f"{path}.ref", "invalid_shape", "origin.ref muss ein String sein")
+
+
+def _check_identity(raw: Any, path: str, col: _Collector) -> None:
+    """Identity muss ein Objekt {feld: wert} sein (FORM; keine Deckungs-Prüfung)."""
+    if not isinstance(raw, dict):
+        col.add(path, "invalid_shape", "identity muss ein Objekt {feld: wert} sein")
+
+
+def _check_facts(raw: Any, plan: dict, col: _Collector) -> None:
+    if raw is None:
+        return  # facts dürfen fehlen
+    if not isinstance(raw, list):
+        col.add("facts", "invalid_shape", "facts muss eine Liste sein")
+        return
+    for i, item in enumerate(raw):
+        path = f"facts[{i}]"
+        if not isinstance(item, dict):
+            col.add(path, "invalid_shape", "jeder Fakt muss ein Objekt sein")
+            continue
+        col.unknown_keys(item, _FACT_KEYS, path)
+        if not isinstance(item.get("entity"), str) or not item.get("entity"):
+            col.add(f"{path}.entity", "invalid_shape", "entity muss ein nicht-leerer String sein")
+        _check_identity(item.get("identity"), f"{path}.identity", col)
+        if not isinstance(item.get("property"), str) or not item.get("property"):
+            col.add(f"{path}.property", "invalid_shape", "property muss ein nicht-leerer String sein")
+        if "value" not in item:
+            col.add(f"{path}.value", "missing_value", "Fakt braucht einen 'value'")
+        _check_origin(item.get("origin"), f"{path}.origin", col)
+
+
+def _check_relations(raw: Any, plan: dict, col: _Collector) -> None:
+    if raw is None:
+        return  # relations dürfen fehlen
+    if not isinstance(raw, list):
+        col.add("relations", "invalid_shape", "relations muss eine Liste sein")
+        return
+    for i, item in enumerate(raw):
+        path = f"relations[{i}]"
+        if not isinstance(item, dict):
+            col.add(path, "invalid_shape", "jede Beziehung muss ein Objekt sein")
+            continue
+        col.unknown_keys(item, _RELATION_KEYS, path)
+        if not isinstance(item.get("relation"), str) or not item.get("relation"):
+            col.add(f"{path}.relation", "invalid_shape", "relation muss ein nicht-leerer String sein")
+        _check_endpoint(item.get("from"), f"{path}.from", col)
+        _check_endpoint(item.get("to"), f"{path}.to", col)
+        _check_origin(item.get("origin"), f"{path}.origin", col)
+
+
+def _check_endpoint(raw: Any, path: str, col: _Collector) -> None:
+    """Ein Beziehungs-Endpunkt braucht {entity, identity} (FORM)."""
+    if not isinstance(raw, dict):
+        col.add(path, "invalid_shape", "braucht ein Objekt {entity, identity}")
+        return
+    col.unknown_keys(raw, _ENDPOINT_KEYS, path)
+    if not isinstance(raw.get("entity"), str) or not raw.get("entity"):
+        col.add(f"{path}.entity", "invalid_shape", "entity muss ein nicht-leerer String sein")
+    _check_identity(raw.get("identity"), f"{path}.identity", col)
+
+
+def _check_question(plan: dict, col: _Collector) -> None:
+    """Genau EINE Frage: fehlt -> missing_question; Liste -> multiple_questions."""
+    if "question" not in plan:
+        col.add("question", "missing_question", "der Plan braucht genau eine Frage")
+        return
+    raw = plan["question"]
+    if isinstance(raw, list):
+        col.add("question", "multiple_questions", "genau EINE Frage — question ist keine Liste")
+        return
+    if not isinstance(raw, dict):
+        col.add("question", "invalid_shape", "question muss ein Objekt sein")
+        return
+    col.unknown_keys(raw, _QUESTION_KEYS, "question")
+    if not isinstance(raw.get("derivation_id"), str) or not raw.get("derivation_id"):
+        col.add("question.derivation_id", "invalid_shape",
+                "derivation_id muss ein nicht-leerer String sein")
+    subject = raw.get("subject")
+    if not isinstance(subject, dict):
+        col.add("question.subject", "invalid_shape", "subject braucht ein Objekt {entity, identity}")
+        return
+    col.unknown_keys(subject, _ENDPOINT_KEYS, "question.subject")
+    if not isinstance(subject.get("entity"), str) or not subject.get("entity"):
+        col.add("question.subject.entity", "invalid_shape",
+                "entity muss ein nicht-leerer String sein")
+    _check_identity(subject.get("identity"), "question.subject.identity", col)
+
+
+def _check_proposals(raw: Any, plan: dict, col: _Collector) -> None:
+    if raw is None:
+        return  # rule_proposals optional
+    if not isinstance(raw, list):
+        col.add("rule_proposals", "invalid_shape", "rule_proposals muss eine Liste sein")
+        return
+    for i, item in enumerate(raw):
+        path = f"rule_proposals[{i}]"
+        if not isinstance(item, dict):
+            col.add(path, "invalid_shape", "jeder Vorschlag muss ein Objekt sein")
+            continue
+        col.unknown_keys(item, _PROPOSAL_KEYS, path)
+        # Grobform: id str, head dict, when list. Die Regel-Grammatik selbst prüft
+        # der Server (build_rule_expr) — der Client kennt sie nicht.
+        if not isinstance(item.get("id"), str) or not item.get("id"):
+            col.add(f"{path}.id", "invalid_shape", "id muss ein nicht-leerer String sein")
+        if not isinstance(item.get("head"), dict):
+            col.add(f"{path}.head", "invalid_shape", "head muss ein Objekt sein")
+        if not isinstance(item.get("when"), list):
+            col.add(f"{path}.when", "invalid_shape", "when muss eine Liste sein")
+
+
+def attach_plan(span: Any, plan: Any) -> AttachResult:
+    """Prüft die FORM und hängt einen gültigen Plan als Span-Attribut an.
+
+    (1) ``validate_plan_shape``; bei Fehlern KEIN Attribut, ``ok=False``.
+    (2) Erfolg: deterministische Serialisierung
+        (``json.dumps(plan, ensure_ascii=False, sort_keys=True)``) und
+        ``span.set_attribute(PLAN_ATTRIBUTE_KEY, serialized)``.
+    (3) Doppel-Anhang auf DEMSELBEN Span scheitert (``already_attached``), das
+        vorhandene Attribut bleibt unverändert (kein Überschreiben).
+    (4) Ein bereits beendeter Span (``is_recording()`` false) scheitert laut
+        (``span_not_recording``) — OpenTelemetry würde das Attribut sonst still
+        verschlucken.
+    """
+    if span in _ATTACHED:
+        return AttachResult(
+            ok=False,
+            errors=[ShapeError(
+                path="", code="already_attached",
+                message="an diesem Span hängt bereits ein meander.plan-Attribut; "
+                        "kein Überschreiben",
+            )],
+        )
+
+    # Beendete Spans nehmen keine Attribute mehr an (OTel setzt sie still nicht).
+    # hasattr-abgesichert, falls ein Span-artiges Objekt kein is_recording() hat.
+    is_recording = getattr(span, "is_recording", None)
+    if callable(is_recording) and not is_recording():
+        return AttachResult(
+            ok=False,
+            errors=[ShapeError(
+                path="", code="span_not_recording",
+                message="Span ist nicht mehr beschreibbar",
+            )],
+        )
+
+    errors = validate_plan_shape(plan)
+    if errors:
+        return AttachResult(ok=False, errors=errors)
+
+    serialized = json.dumps(plan, ensure_ascii=False, sort_keys=True)
+    span.set_attribute(PLAN_ATTRIBUTE_KEY, serialized)
+    _ATTACHED.add(span)
+    return AttachResult(ok=True, serialized=serialized)

meander_agent/openai.py

@@ -0,0 +1,175 @@
+# src/meander_agent/openai.py
+"""Dünnes OpenAI-Agents-SDK-Binding auf den Kern (``meander_run`` / ``finalize``).
+
+SDK-spezifisch ist hier NUR: das ``PlanModel`` (Pydantic-``output_type`` für die
+strukturierte finale Ausgabe), der ``Runner.run``-Aufruf (Run-Ende), das Auslesen
+der strukturierten Ausgabe (``final_output_as``) und die Übersetzung von
+``AgentsException`` auf den neutralen ``error_state``. Baustein, Parsen,
+Formprüfung, Fehler-Sperren, Anhängen und ``RunResult`` kommen ALLE aus dem Kern.
+
+Am echten Install (openai-agents 0.17) verifiziert:
+- ``Runner.run(agent, input)`` / ``Runner.run_sync(...)`` -> ``RunResult`` nur bei
+  Completion, sonst ``agents.exceptions.AgentsException`` (Basis) geworfen.
+- strukturierte Ausgabe via ``Agent(output_type=...)`` +
+  ``result.final_output_as(PlanModel, raise_if_incorrect_type=True)``.
+- Das Plan-Schema (``value: Any``, ``dict``-identity, optionale Felder) ist NICHT
+  strict-kompatibel -> ``output_type = AgentOutputSchema(PlanModel,
+  strict_json_schema=False)`` (sonst UserError am SDK).
+
+Kein meander-Import. Der Root-Span wird vom Kern gehalten; das Binding ruft
+``run.finalize(output, error_state)``, solange er offen ist.
+"""
+from __future__ import annotations
+
+from typing import Any, Literal, Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from meander_agent.core import RunResult, meander_run
+
+
+# --------------------------------------------------------------------------- #
+# PlanModel: Pydantic-output_type für OpenAIs strukturierte finale Ausgabe.
+# Spiegelt das Plan-Format (Schema v1). model_dump(by_alias=True) ergibt einen
+# plan-dict, den der Emitter FORM-prüft ('from' braucht ein Alias).
+# --------------------------------------------------------------------------- #
+class _Origin(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    kind: str
+    ref: Optional[str] = None
+
+
+class _Endpoint(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    entity: str
+    identity: dict[str, str] = Field(default_factory=dict)
+
+
+class _Fact(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    entity: str
+    identity: dict[str, str] = Field(default_factory=dict)
+    property: str
+    value: Any = None
+    origin: Optional[_Origin] = None
+
+
+class _Relation(BaseModel):
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+    relation: str
+    from_: _Endpoint = Field(alias="from")
+    to: _Endpoint
+    origin: Optional[_Origin] = None
+
+
+class _Question(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    derivation_id: str
+    subject: _Endpoint
+
+
+class _RuleProposal(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    id: str
+    head: dict[str, Any] = Field(default_factory=dict)
+    when: list[Any] = Field(default_factory=list)
+
+
+class PlanModel(BaseModel):
+    """Pydantic-Abbild des Plan-Formats (plan_version 1) für ``output_type``."""
+
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+    plan_version: Literal[1] = 1
+    facts: list[_Fact] = Field(default_factory=list)
+    relations: list[_Relation] = Field(default_factory=list)
+    question: _Question
+    rule_proposals: list[_RuleProposal] = Field(default_factory=list)
+
+
+def plan_output_type(plan_model: type[BaseModel] = PlanModel):
+    """Der non-strict ``output_type`` fürs Agent-Objekt (Plan-Schema ist nicht strict)."""
+    from agents import AgentOutputSchema
+
+    return AgentOutputSchema(plan_model, strict_json_schema=False)
+
+
+def _plan_dict(final_output: BaseModel) -> dict:
+    """PlanModel-Instanz -> plan-dict (by_alias, damit 'from'/'to' korrekt heißen)."""
+    return final_output.model_dump(by_alias=True)
+
+
+def _openai_error_state(exc: BaseException) -> dict:
+    """AgentsException (Fehler/Abbruch) -> neutraler error_state (Sperre im Kern)."""
+    return {"exception": type(exc).__name__, "detail": str(exc)}
+
+
+async def run_with_plan_async(
+    task: str,
+    *,
+    vocabulary: Any,
+    tracer: Any,
+    root_span_name: str = "agent.run",
+    plan_model: type[BaseModel] = PlanModel,
+    agent_name: str = "plan-agent",
+) -> RunResult:
+    """Fährt Runner.run mit output_type=PlanModel und finalisiert über den Kern.
+
+    Erfolg -> ``final_output_as(plan_model).model_dump()`` -> ``run.finalize``.
+    Jede ``AgentsException`` (Fehler/Abbruch) -> ``error_state`` -> KEIN Attach.
+    """
+    from agents import Agent, Runner
+    from agents.exceptions import AgentsException
+
+    with meander_run(vocabulary=vocabulary, tracer=tracer, root_span_name=root_span_name) as run:
+        agent = Agent(
+            name=agent_name,
+            instructions=run.prompt_fragment,
+            output_type=plan_output_type(plan_model),
+        )
+        try:
+            result = await Runner.run(agent, task)
+        except AgentsException as exc:
+            return run.finalize(None, error_state=_openai_error_state(exc))
+        try:
+            final = result.final_output_as(plan_model, raise_if_incorrect_type=True)
+        except TypeError as exc:
+            # final_output_as wirft ein reines TypeError (KEIN AgentsException),
+            # wenn die finale Ausgabe nicht der PlanModel-Typ ist (Tool-als-Final-
+            # Output-/Handoff-Pfade). Auch das ist ein Fehlerausgang -> Sperre über
+            # den Kern, nie ein Roh-Crash beim Aufrufer.
+            return run.finalize(None, error_state=_openai_error_state(exc))
+        return run.finalize(_plan_dict(final), error_state=None)
+
+
+def run_with_plan(
+    task: str,
+    *,
+    vocabulary: Any,
+    tracer: Any,
+    root_span_name: str = "agent.run",
+    plan_model: type[BaseModel] = PlanModel,
+    agent_name: str = "plan-agent",
+) -> RunResult:
+    """Synchroner Weg über ``Runner.run_sync`` (deterministische Nutzung)."""
+    from agents import Agent, Runner
+    from agents.exceptions import AgentsException
+
+    with meander_run(vocabulary=vocabulary, tracer=tracer, root_span_name=root_span_name) as run:
+        agent = Agent(
+            name=agent_name,
+            instructions=run.prompt_fragment,
+            output_type=plan_output_type(plan_model),
+        )
+        try:
+            result = Runner.run_sync(agent, task)
+        except AgentsException as exc:
+            return run.finalize(None, error_state=_openai_error_state(exc))
+        try:
+            final = result.final_output_as(plan_model, raise_if_incorrect_type=True)
+        except TypeError as exc:
+            # final_output_as wirft ein reines TypeError (KEIN AgentsException),
+            # wenn die finale Ausgabe nicht der PlanModel-Typ ist (Tool-als-Final-
+            # Output-/Handoff-Pfade). Auch das ist ein Fehlerausgang -> Sperre über
+            # den Kern, nie ein Roh-Crash beim Aufrufer.
+            return run.finalize(None, error_state=_openai_error_state(exc))
+        return run.finalize(_plan_dict(final), error_state=None)

meander_agent/transport.py

@@ -0,0 +1,85 @@
+# src/meander_agent/transport.py
+"""Transport-Setup: OTel-Tracing + OTLP/HTTP-Export auf den meander-Ingress.
+
+``init_meander(endpoint, source_key)`` ist für Kunden ohne eigenes OTel der
+einzige nötige Aufruf: er baut einen EIGENEN TracerProvider samt OTLP/HTTP-
+Exporter auf den meander-Ingress und gibt einen ``MeanderClient`` zurück. Kein
+stilles globales ``set_tracer_provider`` — der Client hält seinen eigenen
+Provider. Kunden mit bestehendem Tracing nutzen stattdessen ``meander_run(...,
+tracer=ihr_tracer)`` direkt; das Paket erzwingt keinen Provider.
+
+Der Run-Root-Span wird nicht hier, sondern über den Kern-Kontextmanager geöffnet
+(``client.run(vocabulary=...)`` / ``meander_run``, Block B).
+"""
+from __future__ import annotations
+
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.sdk.trace import TracerProvider
+
+
+class MeanderClient:
+    """Transport-Griff: hält den eigenen Provider/Tracer für den meander-Export."""
+
+    def __init__(self, tracer, provider: TracerProvider) -> None:
+        self._tracer = tracer
+        self._provider = provider
+
+    @property
+    def tracer(self):
+        """Der auf den meander-Ingress verdrahtete Tracer (für ``meander_run``)."""
+        return self._tracer
+
+    def run(self, *, vocabulary, root_span_name: str = "agent.run"):
+        """Zucker: ``meander_run`` an den eigenen Tracer gebunden.
+
+        ``with client.run(vocabulary=...) as run:`` öffnet den Run-Root-Span über
+        den Kern-Kontextmanager auf dem verdrahteten Tracer.
+        """
+        from meander_agent.core import meander_run
+
+        return meander_run(
+            vocabulary=vocabulary, tracer=self._tracer, root_span_name=root_span_name
+        )
+
+    def force_flush(self, timeout_millis: int = 30_000) -> bool:
+        """Exportiert anstehende Spans sofort (nützlich für kurze Skripte/Tests)."""
+        return self._provider.force_flush(timeout_millis)
+
+    def shutdown(self) -> None:
+        """Fährt den eigenen Provider herunter (flusht dabei den Exporter)."""
+        self._provider.shutdown()
+
+
+def init_meander(
+    endpoint: str,
+    source_key: str,
+    *,
+    service_name: str = "meander-agent",
+) -> MeanderClient:
+    """Richtet Tracing + OTLP/HTTP-Export auf den meander-Ingress ein.
+
+    ``endpoint`` = die VOLLE OTLP-Traces-URL
+    (``…/api/sources/<source_id>/v1/traces``); ``source_key`` = Bearer-Token
+    dieser Source. KEIN URL-Building hier. Leerer ``endpoint``/``source_key`` ->
+    ``ValueError`` (laut, nie still). KEIN globales Provider-Setzen.
+    """
+    if not endpoint or not endpoint.strip():
+        raise ValueError(
+            "init_meander braucht eine nicht-leere OTLP-Traces-URL (endpoint), "
+            "z.B. https://<host>/api/sources/<source_id>/v1/traces"
+        )
+    if not source_key or not source_key.strip():
+        raise ValueError("init_meander braucht einen nicht-leeren source_key (Bearer-Token)")
+
+    provider = TracerProvider(resource=Resource.create({"service.name": service_name}))
+    exporter = OTLPSpanExporter(
+        endpoint=endpoint,
+        headers={"authorization": f"Bearer {source_key}"},
+    )
+    # BatchSpanProcessor lazily importiert, damit der Import-Pfad schlank bleibt.
+    from opentelemetry.sdk.trace.export import BatchSpanProcessor
+
+    provider.add_span_processor(BatchSpanProcessor(exporter))
+    tracer = provider.get_tracer("meander-agent")
+    return MeanderClient(tracer=tracer, provider=provider)

meander_agent-0.1.0.dist-info/METADATA

@@ -0,0 +1,229 @@
+Metadata-Version: 2.4
+Name: meander-agent
+Version: 0.1.0
+Summary: Client-side meander.plan SDK: transport setup + a form-checked plan onto a real OTel span, with thin Claude/OpenAI bindings. Imports meander NOT.
+Author-email: Raphael Feikert <r.feikert@symbolic-intelligence.de>
+Requires-Python: >=3.11
+Requires-Dist: opentelemetry-exporter-otlp-proto-http<2,>=1.30
+Requires-Dist: opentelemetry-sdk<2,>=1.30
+Provides-Extra: claude
+Requires-Dist: claude-agent-sdk<0.3,>=0.2; extra == 'claude'
+Provides-Extra: openai
+Requires-Dist: openai-agents<0.18,>=0.17; extra == 'openai'
+Provides-Extra: test
+Requires-Dist: pytest-randomly>=3; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# meander-agent
+
+Kundenseitiges SDK für die **Plan-Sende-Seite** von meander. Dein Agent hält
+fest, was er getan hat, als nachvollziehbare Behauptung mit Herkunft, und stellt
+GENAU EINE Frage an eine Regel deiner Ontologie. Das Paket baut daraus ein
+`meander.plan`, prüft dessen FORM und hängt es an einen echten OpenTelemetry-Span,
+den dein OTLP-Export zu meander trägt. Kein meander-Import, keine Ontologie im
+Client.
+
+## Das Modell in einem Absatz
+
+Ein `meander.plan` ist eine **Behauptung plus eine Frage**, keine Entscheidung:
+
+- **facts** — was der Agent beobachtet/eingeschätzt hat. Jeder Fakt trägt SEINE
+  Herkunft (`origin.kind`: `tool` | `api` | `human` | `agent`). Ein Tool-Ergebnis
+  ist `tool`, die eigene Einschätzung des Agenten ist `agent`.
+- **relations** — behauptete Beziehungen zwischen Entities (optional).
+- **question** — GENAU EINE Frage an eine bestehende Derivation (Regel) deiner
+  Welt, z.B. „gilt hier `requires_review`?". Der Agent **entscheidet nicht**; ob
+  die Regel greift, bestimmt meander serverseitig, und ein Mensch prüft.
+
+Der Client prüft nur die **FORM** (Pflichtfelder, Typen, genau eine Frage,
+`origin`-Vokabular, `plan_version == 1`). Ob die Entities/Properties/Derivations
+wirklich existieren, weiß nur der Server (er kennt deine Ontologie). Darum
+importiert dieses Paket meander NICHT und lädt keine Ontologie.
+
+**Garantien (nie stilles Nichtstun):** ein Fehlerlauf hängt NIE ein Attribut an;
+ein nicht mehr beschreibbarer Span verweigert das Attribut laut
+(`AttachResult(ok=False, span_not_recording)`); ein formfehlerhafter Plan wird mit
+Feldpfad gemeldet, statt halb geschrieben zu werden.
+
+## Installation
+
+```
+pip install meander-agent            # Transport + Emitter (schlank, ohne LLM-SDK)
+pip install "meander-agent[claude]"  # + Claude-Agent-SDK-Binding
+pip install "meander-agent[openai]"  # + OpenAI-Agents-SDK-Binding
+```
+
+## 1. Dein Vokabular deklarieren
+
+Du gibst dem Agenten die Namen deiner Welt (er soll nichts erfinden). Je Entity
+ihre identity-Felder und Properties, je Relation ihre Endpunkte, plus die
+Derivation-IDs, die er befragen darf:
+
+```python
+vocabulary = {
+    "entities": {
+        "Order":   {"identity": ["order_id"], "properties": ["amount", "risk"]},
+        "Case":    {"identity": ["case_id"],  "properties": []},
+        "Outcome": {"identity": ["outcome_id"], "properties": []},
+    },
+    "relations": {
+        "concerns": {"from": "Case", "to": "Order"},
+    },
+    "derivation_ids": ["requires_review.high_value"],
+}
+```
+
+Daraus erzeugt das Paket den Prompt-Baustein (nennt dem Modell nur diese Namen)
+und das JSON-Schema der strukturierten Ausgabe (erlaubt nur diese Namen).
+
+## 2. Transport einrichten
+
+Ohne eigenes OTel genügt ein Aufruf. `endpoint` ist die volle OTLP-Traces-URL
+deiner Source, `source_key` das Bearer-Token dieser Source:
+
+```python
+from meander_agent import init_meander
+
+client = init_meander(
+    endpoint="https://<host>/api/sources/<source_id>/v1/traces",
+    source_key="<bearer-token>",
+)
+# client.tracer  -> der verdrahtete OTel-Tracer
+# client.shutdown() / client.force_flush()  -> Export abschließen
+```
+
+`init_meander` setzt KEINEN globalen Provider; der Client hält seinen eigenen.
+Hast du bereits ein OTel-Setup, lass `init_meander` weg und übergib deinen Tracer
+direkt (siehe Abschnitt 5).
+
+## 3. Einen Agenten-Run fahren (Claude)
+
+```python
+from meander_agent.claude import run_with_plan
+
+result = run_with_plan(
+    "Bearbeite Bestellung ORD-42. Rufe die üblichen Tools auf, behaupte die "
+    "gewonnenen Fakten mit ihrer Herkunft und stelle GENAU EINE Frage an die "
+    "Derivation requires_review.high_value. Triff KEINE Entscheidung.",
+    vocabulary=vocabulary,
+    tracer=client.tracer,
+)
+print("angehängt" if result.attached else f"kein Plan gesetzt: {result.error_state}")
+client.shutdown()   # Span exportieren
+```
+
+Das Binding öffnet den Root-Span, fährt das Modell mit strukturierter Ausgabe,
+sperrt bei Fehler/Abbruch und hängt bei Erfolg den geprüften Plan an. Es gibt ein
+`RunResult` zurück (siehe Abschnitt 4). Braucht das `[claude]`-Extra und einen
+`ANTHROPIC_API_KEY`.
+
+## 3b. Derselbe Run über OpenAI
+
+Identischer Aufruf, anderes Binding (Extra `[openai]`, `OPENAI_API_KEY`):
+
+```python
+from meander_agent.openai import run_with_plan
+
+result = run_with_plan(task, vocabulary=vocabulary, tracer=client.tracer)
+```
+
+Beide Bindings gibt es auch async (`run_with_plan_async`).
+
+## 4. Was du zurückbekommst
+
+`RunResult`:
+
+- `attached: bool` — wurde `meander.plan` an den Span gehängt?
+- `plan: dict | None` — der angehängte Plan (bei Erfolg).
+- `shape_errors: list[ShapeError]` — Formfehler mit `path` / `code` / `message`,
+  falls die Ausgabe die FORM-Prüfung nicht bestand.
+- `error_state` — `None` bei Erfolg; sonst der Fehlerausgang des Laufs
+  (SDK-Fehler, Abbruch, Typ-Mismatch). Ist er gesetzt, wird NIE angehängt.
+
+Kein `meander.plan` heißt also immer: entweder ein Fehlerlauf (`error_state`) oder
+eine formfehlerhafte Ausgabe (`shape_errors`) — beides steht im Ergebnis, nichts
+verschwindet still.
+
+## 5. Eigenes Tracing / eigenes SDK (der Kern)
+
+Willst du dein eigenes SDK anbinden (oder deinen eigenen Tracer nutzen), fährst du
+den SDK-neutralen Kontextmanager selbst. Er liefert dir den Baustein und das
+Schema und übernimmt Parsen, Formprüfung, Sperren und Anhängen:
+
+```python
+from meander_agent import meander_run
+
+with meander_run(vocabulary=vocabulary, tracer=my_tracer) as run:
+    # run.prompt_fragment : Format + erlaubtes Vokabular -> als Instruktion ans SDK
+    # run.output_schema   : JSON-Schema, falls dein SDK strukturierte Ausgabe kann
+    output, error = call_your_llm(task, instructions=run.prompt_fragment,
+                                  schema=run.output_schema)
+    # output: das strukturierte Ergebnis (dict) ODER ein reiner JSON-String.
+    # error_state: None bei Erfolg, sonst ein beliebiges Detail (=> Sperre).
+    result = run.finalize(output, error_state=error)
+```
+
+Der Kern übergibt nie selbst Prompts ans SDK und liest nie SDK-Resultate — das ist
+Sache deines Bindings. Genauso arbeiten die mitgelieferten Claude-/OpenAI-Bindings.
+
+## 6. Deterministischer Plan ohne LLM
+
+Baust du den Plan selbst (Tests, regelbasierte Agenten, auth-loser Pfad), nutzt du
+den Emitter direkt:
+
+```python
+from meander_agent import attach_plan, validate_plan_shape
+
+plan = {
+    "plan_version": 1,
+    "facts": [
+        {"entity": "Order", "identity": {"order_id": "ORD-42"},
+         "property": "amount", "value": 900,
+         "origin": {"kind": "tool", "ref": "lookup_order"}},
+    ],
+    "relations": [
+        {"relation": "concerns",
+         "from": {"entity": "Case", "identity": {"case_id": "C-1"}},
+         "to":   {"entity": "Order", "identity": {"order_id": "ORD-42"}},
+         "origin": {"kind": "agent"}},
+    ],
+    "question": {
+        "derivation_id": "requires_review.high_value",
+        "subject": {"entity": "Case", "identity": {"case_id": "C-1"}},
+    },
+}
+
+errors = validate_plan_shape(plan)            # reine FORM-Prüfung (leer = ok)
+with client.tracer.start_as_current_span("agent.run") as span:
+    res = attach_plan(span, plan)             # hängt bei Formgültigkeit an
+    if not res.ok:
+        print("nicht angehängt:", [e.as_dict() for e in res.errors])
+client.shutdown()
+```
+
+## Öffentliche Fläche
+
+| Symbol | Zweck |
+|---|---|
+| `init_meander(endpoint, source_key) -> MeanderClient` | Transport (OTel + OTLP) einrichten |
+| `MeanderClient.tracer / .run(vocabulary=…) / .force_flush() / .shutdown()` | Tracer, Kern-Zucker, Export |
+| `meander_agent.claude.run_with_plan[_async](task, *, vocabulary, tracer)` | Claude-Binding |
+| `meander_agent.openai.run_with_plan[_async](task, *, vocabulary, tracer)` | OpenAI-Binding |
+| `meander_run(vocabulary, tracer) -> Run` | SDK-neutraler Kern-Kontextmanager |
+| `Run.prompt_fragment / .output_schema / .finalize(output, error_state)` | Bausteine + Verarbeitung |
+| `attach_plan(span, plan) -> AttachResult` | FORM-Prüfung + Anhang |
+| `validate_plan_shape(plan) -> list[ShapeError]` | reine FORM-Prüfung |
+| `RunResult`, `AttachResult`, `ShapeError` | Ergebnis-/Fehlertypen |
+| `PLAN_ATTRIBUTE_KEY`, `ORIGIN_KINDS`, `PLAN_VERSION` | Client-Konstanten |
+
+## Entwicklung
+
+```
+pixi run test          # zufällige Reihenfolge (pytest-randomly)
+pixi run -- pytest -p no:randomly    # feste Reihenfolge
+```
+
+Die credential-gated Live-LLM-Tests (Claude/OpenAI) laufen dort, wo die Keys
+gesetzt sind, und werden sonst übersprungen; die deterministische Suite läuft
+immer und ohne Mocks.

meander_agent-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+meander_agent/__init__.py,sha256=FwT-xAOXwAOR5mgSD_2la7ywHFScO_bdtRMwFUpLptc,1350
+meander_agent/claude.py,sha256=KbiDA6oBdbw4Vr2pSKUG1Tsd63zRo3FvAM_aP10Cme4,3987
+meander_agent/core.py,sha256=Y2iFvGukMmjmKTMkG3m3IZcNqzuvfV8mZyZhFuCnhKw,16023
+meander_agent/emitter.py,sha256=15VRDrsbO7btNP5Yrgr7MuirwQHHRhy4yIhkoIfvIpk,13310
+meander_agent/openai.py,sha256=cnMjurSvpyCtfMfgyYw17AQBhyL5e6udFqNcSKlSxN8,6865
+meander_agent/transport.py,sha256=VlO0I-iTSQ50H70oJNmlB3gC2ntrsayzvW52IS4yynE,3542
+meander_agent-0.1.0.dist-info/METADATA,sha256=W9ddljb4Lm0qq0BMxuzMaQjZW9U4OunktAJCBqnS5wA,9324
+meander_agent-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+meander_agent-0.1.0.dist-info/RECORD,,

meander_agent-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any