agentpanel 0.1.0__py3-none-any.whl

agentpanel/__init__.py

@@ -0,0 +1,22 @@
+"""Domain-agnostic multi-agent orchestration core."""
+
+from agentpanel.agents import Coordinator, Reviewer, Specialist
+from agentpanel.graph import Workflow, WorkflowResult
+from agentpanel.llm_agents import LLMReviewer, LLMSpecialist
+from agentpanel.state import AgentContext, Artifact, Review, Verdict
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AgentContext",
+    "Artifact",
+    "Coordinator",
+    "LLMReviewer",
+    "LLMSpecialist",
+    "Review",
+    "Reviewer",
+    "Specialist",
+    "Verdict",
+    "Workflow",
+    "WorkflowResult",
+]

agentpanel/agents.py

@@ -0,0 +1,38 @@
+"""Agent contracts: specialists, reviewers, and coordinators.
+
+Agents return plain values; the workflow stamps authorship and round numbers.
+One object may implement several roles, e.g. a specialist that also peer-reviews.
+"""
+
+from typing import Any, Protocol
+
+from agentpanel.state import AgentContext, Artifact, Verdict
+
+
+class Specialist(Protocol):
+    """Produces one artifact per round. On revision rounds, `ctx.feedback_for(self.name)`
+    holds the rejections to address and `ctx.artifacts[self.name]` the previous attempt."""
+
+    @property
+    def name(self) -> str: ...
+
+    @property
+    def kind(self) -> str: ...
+
+    async def produce(self, ctx: AgentContext) -> Any: ...
+
+
+class Reviewer(Protocol):
+    """Judges another agent's artifact. Never asked to review its own."""
+
+    @property
+    def name(self) -> str: ...
+
+    async def review(self, artifact: Artifact, ctx: AgentContext) -> Verdict: ...
+
+
+class Coordinator(Protocol):
+    """Assembles the final result once reviews are settled. `ctx.unresolved` lists
+    artifacts that still had rejections when the revision budget ran out."""
+
+    async def assemble(self, ctx: AgentContext) -> Any: ...

agentpanel/config.py

@@ -0,0 +1,126 @@
+"""Settings loaded from environment variables and an optional `.env` file.
+
+Applications subclass `LLMSettings` to use their own env prefix, e.g.::
+
+    class MyAppSettings(LLMSettings):
+        model_config = SettingsConfigDict(env_prefix="MY_APP_")
+"""
+
+from typing import Literal, Self, get_args
+
+from pydantic import Field, SecretStr
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+Provider = Literal["ollama", "openai", "anthropic"]
+
+DEFAULT_MODELS: dict[Provider, str] = {
+    "ollama": "qwen3:8b",
+    "openai": "gpt-5-mini",
+    "anthropic": "claude-sonnet-5-5",
+}
+DEFAULT_OLLAMA_URL = "http://localhost:11434"
+
+# Cloud keys use each vendor's standard variable name, not the app prefix,
+# so keys users already have in their environment just work.
+API_KEY_ENV_VARS: dict[Provider, str] = {
+    "openai": "OPENAI_API_KEY",
+    "anthropic": "ANTHROPIC_API_KEY",
+}
+
+
+class LLMSettings(BaseSettings):
+    """Which LLM to talk to and how."""
+
+    model_config = SettingsConfigDict(
+        env_prefix="AGENTPANEL_",
+        env_file=".env",
+        extra="ignore",
+        populate_by_name=True,
+    )
+
+    provider: Provider = "ollama"
+    model: str | None = Field(default=None, description="Defaults per provider if unset.")
+    base_url: str | None = Field(
+        default=None,
+        description="Endpoint override for the selected provider, e.g. an "
+        "OpenAI-compatible server. Wins over ollama_url.",
+    )
+    ollama_url: str = Field(
+        default=DEFAULT_OLLAMA_URL,
+        description="Where Ollama runs. Only used when the provider is ollama, so it is "
+        "safe to set globally (e.g. in a container).",
+    )
+    temperature: float | None = Field(
+        default=None, description="Unset means the provider's default."
+    )
+    timeout: float | None = Field(
+        default=None,
+        description="Per-request timeout in seconds. Unset: 600 for Ollama (local models are "
+        "slow and serve one request at a time), 120 for cloud providers.",
+    )
+    context_window: int = Field(
+        default=16_384,
+        description="Ollama only: tokens of context. Ollama's own default is small and "
+        "silently truncates long prompts.",
+    )
+
+    reasoning: bool | None = Field(
+        default=None,
+        description="Ollama only: True/False turns a reasoning model's thinking on/off; "
+        "unset uses the model's default. Off is much faster for structured generation.",
+    )
+
+    agent_models: dict[str, str] = Field(
+        default_factory=dict,
+        description='Per-agent overrides as JSON, e.g. {"reviewer": "anthropic:claude-sonnet-5-5"} '
+        'or {"stubs": "qwen3:14b"}. A known provider prefix switches provider.',
+    )
+    agent_reasoning: dict[str, bool] = Field(
+        default_factory=dict,
+        description='Per-agent `reasoning` overrides as JSON, e.g. {"reviewer": true}.',
+    )
+
+    openai_api_key: SecretStr | None = Field(default=None, validation_alias="OPENAI_API_KEY")
+    anthropic_api_key: SecretStr | None = Field(default=None, validation_alias="ANTHROPIC_API_KEY")
+
+    def for_agent(self, name: str) -> Self:
+        """Settings for one agent, applying any `agent_models` / `agent_reasoning` override."""
+        update: dict[str, object] = {}
+        if name in self.agent_reasoning:
+            update["reasoning"] = self.agent_reasoning[name]
+        spec = self.agent_models.get(name)
+        if spec is not None:
+            provider, sep, model = spec.partition(":")
+            if sep and provider in get_args(Provider):
+                update["model"] = model
+                if provider != self.provider:
+                    # base_url belongs to the original provider; don't leak it to another one
+                    update |= {"provider": provider, "base_url": None}
+            else:
+                update["model"] = spec
+        return self.model_copy(update=update) if update else self
+
+    @property
+    def resolved_model(self) -> str:
+        return self.model or DEFAULT_MODELS[self.provider]
+
+    @property
+    def resolved_timeout(self) -> float:
+        if self.timeout is not None:
+            return self.timeout
+        return 600.0 if self.provider == "ollama" else 120.0
+
+    @property
+    def resolved_base_url(self) -> str | None:
+        if self.base_url:
+            return self.base_url.rstrip("/")
+        return self.ollama_url.rstrip("/") if self.provider == "ollama" else None
+
+    @property
+    def api_key(self) -> SecretStr | None:
+        """The key for the selected provider (None for Ollama)."""
+        if self.provider == "openai":
+            return self.openai_api_key
+        if self.provider == "anthropic":
+            return self.anthropic_api_key
+        return None

agentpanel/graph.py

@@ -0,0 +1,180 @@
+"""Builds the LangGraph workflow: parallel specialists, cross-review, bounded revision
+rounds, then coordinator assembly.
+
+    START -> specialists (parallel) -> gather -> review (one task per reviewer x artifact)
+          -> decide -> [rejected specialists revise | coordinator] -> END
+"""
+
+import re
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass
+from typing import Any, Protocol, TypedDict, cast
+
+from langchain_core.runnables import RunnableConfig
+from langgraph.graph import END, START, StateGraph
+from langgraph.types import Send
+
+from agentpanel.agents import Coordinator, Reviewer, Specialist
+from agentpanel.state import AgentContext, Artifact, Review, WorkflowState
+
+RESERVED_NAMES = frozenset({"gather", "review", "decide", "coordinator"})
+_NAME_PATTERN = re.compile(r"^[a-z][a-z0-9_]*$")
+_STEPS_PER_ROUND = 4  # specialists, gather, review, decide
+
+UpdateCallback = Callable[[str, dict[str, Any]], None]
+
+
+class _Node(Protocol):
+    async def __call__(self, state: WorkflowState) -> dict[str, Any]: ...
+
+
+class _ReviewTask(TypedDict):
+    reviewer: str
+    target: str
+    context: AgentContext
+
+
+@dataclass(frozen=True)
+class WorkflowResult:
+    result: Any
+    artifacts: dict[str, Artifact]
+    reviews: list[Review]
+    rounds: int  # revision rounds used
+    unresolved: list[str]
+
+
+class Workflow:
+    def __init__(
+        self,
+        *,
+        specialists: Sequence[Specialist],
+        coordinator: Coordinator,
+        reviewers: Sequence[Reviewer] = (),
+        max_revisions: int = 1,
+    ) -> None:
+        if not specialists:
+            raise ValueError("A workflow needs at least one specialist.")
+        if max_revisions < 0:
+            raise ValueError("max_revisions must be >= 0.")
+        _validate_names([s.name for s in specialists], "specialist")
+        _validate_names([r.name for r in reviewers], "reviewer")
+
+        self._specialists = {s.name: s for s in specialists}
+        self._reviewers = {r.name: r for r in reviewers}
+        self._coordinator = coordinator
+        self.max_revisions = max_revisions
+        self.graph = self._build().compile()
+
+    async def run(
+        self, inputs: Mapping[str, Any], on_update: UpdateCallback | None = None
+    ) -> WorkflowResult:
+        """Run to completion. `on_update(node, update)` is called as each node finishes,
+        e.g. ("stubs", {"artifacts": ...}) or ("review", {"reviews": [Review]})."""
+        initial: WorkflowState = {
+            "inputs": dict(inputs),
+            "artifacts": {},
+            "reviews": [],
+            "round": 0,
+            "revise": [],
+            "result": None,
+        }
+        config: RunnableConfig = {
+            "recursion_limit": _STEPS_PER_ROUND * (self.max_revisions + 1) + 5
+        }
+        final: Any = None
+        async for mode, chunk in self.graph.astream(
+            initial, config, stream_mode=["updates", "values"]
+        ):
+            if mode == "values":
+                final = chunk
+            elif on_update is not None:
+                for node, update in cast(dict[str, Any], chunk).items():
+                    on_update(node, update or {})
+        final = cast(WorkflowState, final)
+        return WorkflowResult(
+            result=final["result"],
+            artifacts=final["artifacts"],
+            reviews=final["reviews"],
+            rounds=final["round"],
+            unresolved=AgentContext.from_state(final).unresolved,
+        )
+
+    def _build(self) -> StateGraph[WorkflowState]:
+        graph = StateGraph(WorkflowState)
+        for name, specialist in self._specialists.items():
+            graph.add_node(name, self._specialist_node(specialist))
+            graph.add_edge(START, name)
+            graph.add_edge(name, "gather")
+        graph.add_node("gather", _noop)
+        graph.add_node("review", self._review, input_schema=_ReviewTask)
+        graph.add_node("decide", self._decide)
+        graph.add_node("coordinator", self._assemble)
+
+        graph.add_conditional_edges("gather", self._route_reviews, ["review", "decide"])
+        graph.add_edge("review", "decide")
+        graph.add_conditional_edges(
+            "decide", _route_after_decide, [*self._specialists, "coordinator"]
+        )
+        graph.add_edge("coordinator", END)
+        return graph
+
+    def _specialist_node(self, specialist: Specialist) -> _Node:
+        async def node(state: WorkflowState) -> dict[str, Any]:
+            content = await specialist.produce(AgentContext.from_state(state))
+            artifact = Artifact(
+                author=specialist.name, kind=specialist.kind, content=content, round=state["round"]
+            )
+            return {"artifacts": {specialist.name: artifact}}
+
+        return node
+
+    def _route_reviews(self, state: WorkflowState) -> list[Send] | str:
+        context = AgentContext.from_state(state)
+        fresh = [a for a in state["artifacts"].values() if a.round == state["round"]]
+        tasks = [
+            Send("review", _ReviewTask(reviewer=name, target=artifact.author, context=context))
+            for artifact in fresh
+            for name in self._reviewers
+            if name != artifact.author
+        ]
+        return tasks or "decide"
+
+    async def _review(self, state: _ReviewTask) -> dict[str, Any]:
+        artifact = state["context"].artifacts[state["target"]]
+        verdict = await self._reviewers[state["reviewer"]].review(artifact, state["context"])
+        review = Review(
+            reviewer=state["reviewer"],
+            target=artifact.author,
+            round=artifact.round,
+            approved=verdict.approved,
+            comments=verdict.comments,
+        )
+        return {"reviews": [review]}
+
+    async def _decide(self, state: WorkflowState) -> dict[str, Any]:
+        rejected = AgentContext.from_state(state).unresolved
+        if rejected and state["round"] < self.max_revisions:
+            return {"round": state["round"] + 1, "revise": rejected}
+        return {"revise": []}
+
+    async def _assemble(self, state: WorkflowState) -> dict[str, Any]:
+        return {"result": await self._coordinator.assemble(AgentContext.from_state(state))}
+
+
+async def _noop(state: WorkflowState) -> dict[str, Any]:
+    return {}
+
+
+def _route_after_decide(state: WorkflowState) -> list[str] | str:
+    return state["revise"] or "coordinator"
+
+
+def _validate_names(names: list[str], role: str) -> None:
+    for name in names:
+        if not _NAME_PATTERN.match(name):
+            raise ValueError(f"Invalid {role} name {name!r}: use lowercase letters, digits, _.")
+        if name in RESERVED_NAMES:
+            raise ValueError(f"{role.capitalize()} name {name!r} is reserved.")
+    duplicates = sorted({n for n in names if names.count(n) > 1})
+    if duplicates:
+        raise ValueError(f"Duplicate {role} names: {duplicates}")

agentpanel/llm.py

@@ -0,0 +1,139 @@
+"""LLM provider abstraction: Ollama by default, bring-your-own-key for cloud providers.
+
+Provider packages are imported lazily so cloud SDKs stay optional extras.
+"""
+
+import importlib
+import importlib.util
+from dataclasses import dataclass
+from typing import Any, cast
+
+import httpx
+from langchain_core.language_models import BaseChatModel
+
+from agentpanel.config import API_KEY_ENV_VARS, LLMSettings, Provider
+
+# provider -> (module, chat class, pip extra)
+_PROVIDERS: dict[Provider, tuple[str, str, str | None]] = {
+    "ollama": ("langchain_ollama", "ChatOllama", None),
+    "openai": ("langchain_openai", "ChatOpenAI", "openai"),
+    "anthropic": ("langchain_anthropic", "ChatAnthropic", "anthropic"),
+}
+
+
+class LLMConfigError(Exception):
+    """The configured provider cannot be used as-is. The message says how to fix it."""
+
+
+class ProviderNotInstalledError(LLMConfigError):
+    pass
+
+
+class MissingAPIKeyError(LLMConfigError):
+    pass
+
+
+def create_chat_model(settings: LLMSettings | None = None) -> BaseChatModel:
+    """Build a LangChain chat model for the configured provider. Makes no network calls."""
+    settings = settings or LLMSettings()
+    if settings.provider != "ollama" and settings.api_key is None:
+        env_var = API_KEY_ENV_VARS[settings.provider]
+        raise MissingAPIKeyError(
+            f"Provider '{settings.provider}' needs an API key. Set {env_var} "
+            "in your environment or .env file."
+        )
+    _, class_name, _ = _PROVIDERS[settings.provider]
+    chat_class = getattr(_import_provider(settings.provider), class_name)
+
+    kwargs: dict[str, Any] = {"model": settings.resolved_model}
+    if settings.temperature is not None:
+        kwargs["temperature"] = settings.temperature
+    if settings.resolved_base_url:
+        kwargs["base_url"] = settings.resolved_base_url
+    if settings.provider == "ollama":
+        kwargs["client_kwargs"] = {"timeout": settings.resolved_timeout}
+        kwargs["num_ctx"] = settings.context_window
+        if settings.reasoning is not None:
+            kwargs["reasoning"] = settings.reasoning
+    else:
+        kwargs["api_key"] = settings.api_key
+        kwargs["timeout"] = settings.resolved_timeout
+
+    return cast(BaseChatModel, chat_class(**kwargs))
+
+
+def _import_provider(provider: Provider) -> Any:
+    module_name, _, extra = _PROVIDERS[provider]
+    try:
+        return importlib.import_module(module_name)
+    except ImportError as exc:
+        package = module_name.replace("_", "-")
+        hint = f"Install `{package}`" + (f" (the `{extra}` extra)." if extra else ".")
+        raise ProviderNotInstalledError(f"Provider '{provider}' is not installed. {hint}") from exc
+
+
+@dataclass(frozen=True)
+class ProviderStatus:
+    ok: bool
+    provider: Provider
+    model: str
+    detail: str
+
+
+def check_provider(
+    settings: LLMSettings | None = None, *, client: httpx.Client | None = None
+) -> ProviderStatus:
+    """Check the configured provider is usable, with an actionable message if not.
+
+    For Ollama this contacts the server and checks the model is pulled. For cloud
+    providers it only checks the package and key are present; it does not spend
+    tokens validating the key.
+    """
+    settings = settings or LLMSettings()
+    model = settings.resolved_model
+
+    def status(ok: bool, detail: str) -> ProviderStatus:
+        return ProviderStatus(ok=ok, provider=settings.provider, model=model, detail=detail)
+
+    module_name, _, extra = _PROVIDERS[settings.provider]
+    if importlib.util.find_spec(module_name) is None:
+        return status(
+            False,
+            f"Package `{module_name.replace('_', '-')}` is not installed (the `{extra}` extra).",
+        )
+
+    if settings.provider != "ollama":
+        env_var = API_KEY_ENV_VARS[settings.provider]
+        if settings.api_key is None:
+            return status(False, f"No API key. Set {env_var} in your environment or .env file.")
+        return status(True, f"{env_var} is set (not validated against the API).")
+
+    return status(*_check_ollama(settings, model, client))
+
+
+def _check_ollama(
+    settings: LLMSettings, model: str, client: httpx.Client | None
+) -> tuple[bool, str]:
+    url = settings.resolved_base_url
+    http = client or httpx.Client(timeout=5.0)
+    try:
+        response = http.get(f"{url}/api/tags")
+        response.raise_for_status()
+        pulled = {m["name"] for m in response.json().get("models", [])}
+    except httpx.HTTPError as exc:
+        return False, (
+            f"Cannot reach Ollama at {url} ({exc.__class__.__name__}). "
+            "Is it running? Start it with `ollama serve`."
+        )
+    finally:
+        if client is None:
+            http.close()
+
+    if _ollama_tag(model) not in {_ollama_tag(name) for name in pulled}:
+        return False, f"Model '{model}' is not pulled. Run `ollama pull {model}`."
+    return True, f"Ollama is running at {url} and '{model}' is available."
+
+
+def _ollama_tag(name: str) -> str:
+    """`qwen3` and `qwen3:latest` refer to the same Ollama model."""
+    return name if ":" in name else f"{name}:latest"

agentpanel/llm_agents.py

@@ -0,0 +1,98 @@
+"""Reusable LLM-backed agents. Applications supply instructions and prompt renderers."""
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+from langchain_core.language_models import BaseChatModel
+from langchain_core.messages import HumanMessage, SystemMessage
+from pydantic import BaseModel
+
+from agentpanel.state import AgentContext, Artifact, Review, Verdict
+from agentpanel.structured import ainvoke_structured, format_content, message_text
+
+REVIEW_GUIDANCE = (
+    "Approve only if the artifact is correct and fit for its purpose. When rejecting, give "
+    "specific, actionable comments: the author revises using only your comments."
+)
+
+
+def render_artifact(artifact: Artifact, ctx: AgentContext) -> str:
+    """Default reviewer prompt: just the artifact."""
+    return (
+        f"Review this {artifact.kind} produced by '{artifact.author}':\n\n"
+        f"<artifact>\n{format_content(artifact.content)}\n</artifact>"
+    )
+
+
+def render_feedback(feedback: list[Review]) -> str:
+    """Reviewer comments as a bullet list, attributed to each reviewer."""
+    return "\n".join(
+        f"- ({review.reviewer}) {comment}"
+        for review in feedback
+        for comment in (review.comments or ["Rejected without comments."])
+    )
+
+
+def render_revision(previous: Artifact, feedback: list[Review]) -> str:
+    return (
+        "Your previous attempt was rejected.\n\n"
+        f"<previous_attempt>\n{format_content(previous.content)}\n</previous_attempt>\n\n"
+        f"Reviewer feedback to address:\n{render_feedback(feedback)}\n\n"
+        "Produce a complete, corrected replacement, not a diff."
+    )
+
+
+@dataclass
+class LLMSpecialist:
+    """Produces text, or an `output_schema` instance when one is given.
+
+    On revision rounds the previous attempt and reviewer feedback are appended to the
+    prompt automatically, so `render` only needs to describe the task.
+    """
+
+    name: str
+    kind: str
+    model: BaseChatModel
+    instructions: str
+    render: Callable[[AgentContext], str]
+    output_schema: type[BaseModel] | None = None
+    check: Callable[[Any], list[str]] | None = None  # domain checks on structured output
+    max_attempts: int = 3
+
+    async def produce(self, ctx: AgentContext) -> Any:
+        messages = [SystemMessage(self.instructions), HumanMessage(self._prompt(ctx))]
+        if self.output_schema is None:
+            return message_text(await self.model.ainvoke(messages))
+        return await ainvoke_structured(
+            self.model,
+            messages,
+            self.output_schema,
+            max_attempts=self.max_attempts,
+            check=self.check,
+        )
+
+    def _prompt(self, ctx: AgentContext) -> str:
+        prompt = self.render(ctx)
+        feedback = ctx.feedback_for(self.name)
+        if not feedback:
+            return prompt
+        return f"{prompt}\n\n{render_revision(ctx.artifacts[self.name], feedback)}"
+
+
+@dataclass
+class LLMReviewer:
+    name: str
+    model: BaseChatModel
+    instructions: str
+    render: Callable[[Artifact, AgentContext], str] = render_artifact
+    max_attempts: int = 3
+
+    async def review(self, artifact: Artifact, ctx: AgentContext) -> Verdict:
+        messages = [
+            SystemMessage(f"{self.instructions}\n\n{REVIEW_GUIDANCE}"),
+            HumanMessage(self.render(artifact, ctx)),
+        ]
+        return await ainvoke_structured(
+            self.model, messages, Verdict, max_attempts=self.max_attempts
+        )

agentpanel/state.py

@@ -0,0 +1,84 @@
+"""Shared graph state: artifacts, reviews, and the read-only context agents receive."""
+
+import operator
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from typing import Annotated, Any, TypedDict
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class Artifact(BaseModel):
+    """One specialist's output for one round."""
+
+    model_config = ConfigDict(frozen=True)
+
+    author: str
+    kind: str
+    content: Any
+    round: int = 0
+
+
+class Verdict(BaseModel):
+    """A reviewer's decision about one artifact. Rejections trigger a revision."""
+
+    model_config = ConfigDict(frozen=True)
+
+    approved: bool = Field(description="True if the artifact is acceptable as-is.")
+    comments: list[str] = Field(
+        default_factory=list, description="Specific, actionable problems or suggestions."
+    )
+
+
+class Review(Verdict):
+    reviewer: str
+    target: str  # author of the reviewed artifact
+    round: int  # round of the reviewed artifact
+
+
+def _merge(left: dict[str, Artifact], right: dict[str, Artifact]) -> dict[str, Artifact]:
+    return {**left, **right}
+
+
+class WorkflowState(TypedDict):
+    inputs: dict[str, Any]
+    artifacts: Annotated[dict[str, Artifact], _merge]  # latest artifact per author
+    reviews: Annotated[list[Review], operator.add]  # every review from every round
+    round: int
+    revise: list[str]  # authors scheduled to revise in the current round
+    result: Any
+
+
+@dataclass(frozen=True)
+class AgentContext:
+    """What an agent can see when it runs."""
+
+    inputs: Mapping[str, Any]
+    artifacts: Mapping[str, Artifact]
+    reviews: Sequence[Review]
+    round: int
+
+    @classmethod
+    def from_state(cls, state: WorkflowState) -> "AgentContext":
+        return cls(
+            inputs=state["inputs"],
+            artifacts=state["artifacts"],
+            reviews=state["reviews"],
+            round=state["round"],
+        )
+
+    def reviews_of(self, author: str) -> list[Review]:
+        """Reviews of `author`'s latest artifact."""
+        artifact = self.artifacts.get(author)
+        if artifact is None:
+            return []
+        return [r for r in self.reviews if r.target == author and r.round == artifact.round]
+
+    def feedback_for(self, author: str) -> list[Review]:
+        """Rejections of `author`'s latest artifact, i.e. what a revision must address."""
+        return [r for r in self.reviews_of(author) if not r.approved]
+
+    @property
+    def unresolved(self) -> list[str]:
+        """Authors whose latest artifact still has at least one rejection."""
+        return sorted(author for author in self.artifacts if self.feedback_for(author))

agentpanel/structured.py

@@ -0,0 +1,146 @@
+"""Structured output that works across providers, including small local models.
+
+The JSON Schema goes in the prompt, the reply is parsed and validated with pydantic,
+and validation errors are fed back to the model for another attempt. On Ollama,
+decoding is additionally constrained to the schema.
+"""
+
+import json
+import re
+from collections.abc import Callable, Sequence
+from typing import Any, TypeVar
+
+from langchain_core.language_models import BaseChatModel
+from langchain_core.messages import AIMessage, BaseMessage, HumanMessage
+from langchain_core.runnables import Runnable
+from langchain_ollama import ChatOllama
+from pydantic import BaseModel, ValidationError
+
+_THINK = re.compile(r"<think>.*?</think>", re.DOTALL)
+_FENCE = re.compile(r"```(?:json)?\s*(.*?)```", re.DOTALL)
+_MAX_ERROR_CHARS = 1500
+
+T = TypeVar("T", bound=BaseModel)
+
+
+class StructuredOutputError(Exception):
+    """The model never produced output that both parsed and passed the checks.
+
+    `value` holds the last reply that parsed but failed `check`, if any, so callers
+    can salvage the valid parts.
+    """
+
+    def __init__(
+        self,
+        schema: type[BaseModel],
+        attempts: int,
+        problem: str,
+        reply: str,
+        value: BaseModel | None = None,
+    ):
+        super().__init__(
+            f"No valid {schema.__name__} after {attempts} attempt(s). Last problem: {problem}"
+        )
+        self.reply = reply
+        self.value = value
+
+
+def strip_reasoning(text: str) -> str:
+    """Drop `<think>...</think>` blocks that reasoning models put in their content."""
+    return _THINK.sub("", text).strip()
+
+
+def message_text(message: BaseMessage) -> str:
+    return strip_reasoning(message.text)
+
+
+def format_content(content: Any) -> str:
+    """Render artifact content for a prompt."""
+    if isinstance(content, str):
+        return content
+    if isinstance(content, BaseModel):
+        return content.model_dump_json(indent=2)
+    return json.dumps(content, indent=2, default=str)
+
+
+def schema_instructions(schema: type[BaseModel]) -> str:
+    return (
+        "Respond with only a JSON object (no prose) that matches this JSON Schema:\n"
+        + json.dumps(schema.model_json_schema(), indent=2)
+    )
+
+
+def parse_reply(text: str, schema: type[T]) -> T:
+    """Validate a reply, tolerating reasoning tags, code fences, and surrounding prose."""
+    text = strip_reasoning(text)
+    candidates = [text]
+    if fenced := _FENCE.search(text):
+        candidates.append(fenced.group(1))
+    start, end = text.find("{"), text.rfind("}")
+    if start != -1 and end > start:
+        candidates.append(text[start : end + 1])
+    error: ValidationError | None = None
+    for candidate in candidates:
+        try:
+            return schema.model_validate_json(candidate)
+        except ValidationError as exc:
+            error = error or exc  # the error for the full reply is the most informative
+    assert error is not None
+    raise error
+
+
+async def ainvoke_structured(
+    model: BaseChatModel,
+    messages: Sequence[BaseMessage],
+    schema: type[T],
+    *,
+    max_attempts: int = 3,
+    check: Callable[[T], list[str]] | None = None,
+) -> T:
+    """Call `model` until its reply validates against `schema` and passes `check`.
+
+    `check` returns domain-level problems (empty list = fine). Schema errors and check
+    problems are both fed back to the model for the next attempt.
+    """
+    if max_attempts < 1:
+        raise ValueError("max_attempts must be >= 1.")
+    runnable = _constrained(model, schema)
+    conversation = _with_instructions(list(messages), schema_instructions(schema))
+    problem = ""
+    text = ""
+    last_value: T | None = None
+    for _ in range(max_attempts):
+        reply = await runnable.ainvoke(conversation)
+        text = message_text(reply)
+        try:
+            value = parse_reply(text, schema)
+        except ValidationError as exc:
+            problem = str(exc)
+        else:
+            problems = check(value) if check else []
+            if not problems:
+                return value
+            last_value = value
+            problem = "\n".join(f"- {p}" for p in problems)
+        conversation += [
+            AIMessage(text),
+            HumanMessage(
+                f"That reply was invalid:\n{problem[:_MAX_ERROR_CHARS]}\n\n"
+                "Respond again with the complete, corrected JSON object."
+            ),
+        ]
+    raise StructuredOutputError(schema, max_attempts, problem, text, last_value)
+
+
+def _constrained(model: BaseChatModel, schema: type[BaseModel]) -> Runnable[Any, BaseMessage]:
+    if isinstance(model, ChatOllama):
+        return model.bind(format=schema.model_json_schema())
+    return model
+
+
+def _with_instructions(messages: list[BaseMessage], instructions: str) -> list[BaseMessage]:
+    """Append to the final user message rather than adding a second one in a row."""
+    last = messages[-1] if messages else None
+    if isinstance(last, HumanMessage) and isinstance(last.content, str):
+        return [*messages[:-1], HumanMessage(f"{last.content}\n\n{instructions}")]
+    return [*messages, HumanMessage(instructions)]

agentpanel/testing.py

@@ -0,0 +1,44 @@
+"""Test helpers for code built on agentpanel."""
+
+from collections.abc import Callable
+from typing import Any
+
+from langchain_core.callbacks import CallbackManagerForLLMRun
+from langchain_core.language_models import BaseChatModel
+from langchain_core.messages import AIMessage, BaseMessage
+from langchain_core.outputs import ChatGeneration, ChatResult
+from pydantic import Field
+
+
+class ScriptedChatModel(BaseChatModel):
+    """Returns canned replies in order (or from `respond`) and records every call.
+
+    `respond(messages)` computes the reply from the prompt instead, which suits models
+    shared by several agents, e.g. a reviewer that sees different artifacts.
+    """
+
+    replies: list[str] = Field(default_factory=list)
+    respond: Callable[[list[BaseMessage]], str] | None = None
+    calls: list[list[BaseMessage]] = Field(default_factory=list)
+    call_kwargs: list[dict[str, Any]] = Field(default_factory=list)
+
+    @property
+    def _llm_type(self) -> str:
+        return "scripted"
+
+    def _generate(
+        self,
+        messages: list[BaseMessage],
+        stop: list[str] | None = None,
+        run_manager: CallbackManagerForLLMRun | None = None,
+        **kwargs: Any,
+    ) -> ChatResult:
+        self.calls.append(list(messages))
+        self.call_kwargs.append(kwargs)
+        if self.respond is not None:
+            text = self.respond(list(messages))
+        elif self.replies:
+            text = self.replies.pop(0)
+        else:
+            raise AssertionError("ScriptedChatModel ran out of replies.")
+        return ChatResult(generations=[ChatGeneration(message=AIMessage(text))])

agentpanel-0.1.0.dist-info/METADATA

@@ -0,0 +1,113 @@
+Metadata-Version: 2.5
+Name: agentpanel
+Version: 0.1.0
+Summary: Domain-agnostic multi-agent orchestration core (LangGraph) with pluggable local/cloud LLM providers.
+Project-URL: Homepage, https://github.com/anzar-ahsan-commits/api-shakedown/tree/main/packages/agentpanel
+Project-URL: Source, https://github.com/anzar-ahsan-commits/api-shakedown
+Project-URL: Issues, https://github.com/anzar-ahsan-commits/api-shakedown/issues
+Author: Anzar Ahsan
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,langgraph,llm,multi-agent,ollama,structured-output
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: langchain-core>=1.0
+Requires-Dist: langchain-ollama>=1.0
+Requires-Dist: langgraph>=1.0
+Requires-Dist: pydantic-settings>=2.4
+Requires-Dist: pydantic>=2.7
+Provides-Extra: anthropic
+Requires-Dist: langchain-anthropic>=1.0; extra == 'anthropic'
+Provides-Extra: cloud
+Requires-Dist: langchain-anthropic>=1.0; extra == 'cloud'
+Requires-Dist: langchain-openai>=1.0; extra == 'cloud'
+Provides-Extra: openai
+Requires-Dist: langchain-openai>=1.0; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# agentpanel
+
+A small, domain-agnostic core for multi-agent LLM workflows on
+[LangGraph](https://github.com/langchain-ai/langgraph):
+
+- **Specialists** produce artifacts in parallel.
+- **Reviewers** judge each other's artifacts; rejections send the author back to revise,
+  with the feedback, for a bounded number of rounds.
+- A **coordinator** assembles the result, including anything still unresolved.
+
+It runs on local models by default ([Ollama](https://ollama.com)), with bring-your-own-key
+OpenAI and Anthropic support, and gets reliable structured output from small models.
+
+```bash
+pip install agentpanel            # Ollama only
+pip install "agentpanel[cloud]"   # plus OpenAI and Anthropic
+```
+
+## Example
+
+```python
+import asyncio
+from agentpanel import AgentContext, LLMReviewer, LLMSpecialist, Workflow
+from agentpanel.config import LLMSettings
+from agentpanel.llm import create_chat_model
+
+model = create_chat_model(LLMSettings())  # qwen3:8b on local Ollama by default
+
+
+class Join:
+    async def assemble(self, ctx: AgentContext) -> str:
+        return ctx.artifacts["writer"].content
+
+
+workflow = Workflow(
+    specialists=[
+        LLMSpecialist(
+            name="writer",
+            kind="product description",
+            model=model,
+            instructions="You write concise product descriptions.",
+            render=lambda ctx: f"Describe {ctx.inputs['product']} in two sentences.",
+        )
+    ],
+    reviewers=[LLMReviewer("editor", model, "You edit marketing copy for accuracy.")],
+    coordinator=Join(),
+    max_revisions=1,
+)
+result = asyncio.run(workflow.run({"product": "a solar-powered kettle"}))
+print(result.result, result.unresolved)
+```
+
+## Pieces
+
+| Module | What it gives you |
+|---|---|
+| `agentpanel.graph` | `Workflow`: parallel specialists, cross-review, bounded revision, progress callbacks |
+| `agentpanel.agents` | `Specialist`, `Reviewer`, `Coordinator` protocols: bring any implementation |
+| `agentpanel.llm_agents` | `LLMSpecialist`, `LLMReviewer`: prompt-driven agents with revision handling |
+| `agentpanel.structured` | `ainvoke_structured`: pydantic-validated output with error feedback and domain `check`s; constrained decoding on Ollama |
+| `agentpanel.llm` | `create_chat_model`, `check_provider`: provider factory and health checks |
+| `agentpanel.config` | `LLMSettings`: env/.env settings, per-agent model and reasoning overrides |
+| `agentpanel.testing` | `ScriptedChatModel`: a deterministic fake chat model for tests |
+
+## Configuration
+
+`LLMSettings` reads `AGENTPANEL_*` environment variables (subclass it to use your own
+prefix): `PROVIDER` (`ollama`, `openai`, `anthropic`), `MODEL`, `BASE_URL`, `TIMEOUT`,
+`REASONING`, `CONTEXT_WINDOW`, `AGENT_MODELS`, `AGENT_REASONING`. Cloud keys use the
+standard `OPENAI_API_KEY` / `ANTHROPIC_API_KEY`.
+
+Built for and used by [API Shakedown](https://github.com/anzar-ahsan-commits/api-shakedown), where the
+source lives. Issues and contributions: see that repository.
+
+## License
+
+MIT

agentpanel-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+agentpanel/__init__.py,sha256=84T1ixNSukwAm94fCYKmf_u8JbeRf2a_c2U3hbfYwu8,537
+agentpanel/agents.py,sha256=SKS9RP37QujnrwQ_LSalcWC63Z7465vMDh9gb6y1PKI,1170
+agentpanel/config.py,sha256=hmW7D_EbGGDdECjhXML0Erv0odIV7EXgDCVuZuE6bjE,4732
+agentpanel/graph.py,sha256=lk-FqhEdEiUtQT3imnDgP-tOsSZoqKV_Ma74eJncxw8,6833
+agentpanel/llm.py,sha256=0iJ44lFmCBNbR5GEUPEzDhyzv-w-oXxuFu5GiUQkg0Q,5073
+agentpanel/llm_agents.py,sha256=Tco213j7lBCj1wDlOeitgaJsUV655perWbxO0C2sQL4,3480
+agentpanel/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+agentpanel/state.py,sha256=OOpjET9zElbqUGgPD6Wg3544am6TQMwNIJvxNt6wZEo,2644
+agentpanel/structured.py,sha256=qFlBuXLtsKun3pGojjBgW41PJPdQdxdErsFYUpmQdUs,5128
+agentpanel/testing.py,sha256=WTGopioc-vUemU4gPb2CkGSH_2nMRncHUTn5y1qLXFk,1615
+agentpanel-0.1.0.dist-info/METADATA,sha256=E86776RvEOvDy1Xp2xU_elc3MubyFr9iXr_hwqoGXdc,4553
+agentpanel-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+agentpanel-0.1.0.dist-info/licenses/LICENSE,sha256=P1Wn2gFhqAYbpMeFoXqSNkoj3-k3Ce2Usfr2dW4PRec,1068
+agentpanel-0.1.0.dist-info/RECORD,,

agentpanel-0.1.0.dist-info/WHEEL

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

agentpanel-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anzar Ahsan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.