openai-420 0.0.1__tar.gz

openai_420-0.0.1/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

openai_420-0.0.1/PKG-INFO

@@ -0,0 +1,16 @@
+Metadata-Version: 2.4
+Name: openai-420
+Version: 0.0.1
+Summary: Grok 4.20's inference-time multi-agent chatroom, rebuilt from scratch — specialist agents debate via tool calls, a captain synthesizes.
+License: Apache-2.0 license
+License-File: LICENSE
+Author: Allen Chou
+Author-email: f1470891079@gmail.com
+Requires-Python: >=3.11,<4
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: openai

openai_420-0.0.1/openai_420/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.0.1"

openai_420-0.0.1/openai_420/agents.py

@@ -0,0 +1,216 @@
+"""The agents that own LLM logic (PRINCIPLES Law 2, 7).
+
+This is the only place that builds a prompt and calls a model. The orchestrator never
+does. Each agent holds its own incremental Conversation (Law 6) and a cursor over the
+shared board.
+
+Async only: every agent method is a coroutine function and the injected client MUST be an
+``openai.AsyncOpenAI``. Synchronous clients are rejected at construction.
+"""
+
+from __future__ import annotations
+
+import re
+
+import openai
+
+from openai_420.conclude import CONCLUDE_TOOL, Conclusion, parse_conclude
+from openai_420.conversation import Conversation
+from openai_420.roster import (
+    ANSWER_MARKER,
+    AgentSpec,
+    captain_system_prompt,
+    specialist_system_prompt,
+)
+from openai_420.scratchpad import Scratchpad
+from openai_420.trace import log_decision
+
+_CONCLUDE_ACK = "Recorded."
+_SELECT_INSTRUCTION = (
+    "The debate is over. Below are the specialists' final answers, numbered. Choose the "
+    "single best one — prefer the version the majority of specialists agree on. Do NOT "
+    "rewrite, merge, or add anything. Output ONLY the number of your choice."
+)
+_FORCE_CONCLUDE = {"type": "function", "function": {"name": "conclude"}}
+_FALLBACK_DIRECTION = (
+    "No clear ruling was produced. Each specialist must give a concrete, complete answer "
+    "so consensus can be judged next round."
+)
+
+
+def extract_answer(output: str) -> str:
+    """The deliverable after the last answer marker; the whole output if the marker is
+    absent. Specialists state their reasoning first, then the marker, then the answer, so
+    the board carries reasons teammates can weigh — but the user only gets the answer.
+    """
+    if ANSWER_MARKER in output:
+        return output.rsplit(ANSWER_MARKER, 1)[1].strip()
+    return output.strip()
+
+
+class Specialist:
+    """A debating specialist. ``respond`` is a coroutine — await it once per round."""
+
+    def __init__(
+        self,
+        *,
+        spec: AgentSpec,
+        roster: list[AgentSpec],
+        client: openai.AsyncOpenAI,
+        model: str,
+        user_query: str,
+    ) -> None:
+        _require_async_client(client)
+        self.name = spec.name
+        self._client = client
+        self._model = model
+        self._conversation = Conversation(
+            system=specialist_system_prompt(spec, roster), user_query=user_query
+        )
+        self._last_seen = 0
+
+    async def respond(self, board: Scratchpad, *, round: int) -> str:
+        delta = board.delta(for_author=self.name, since_round=self._last_seen)
+        if delta:
+            self._conversation.add_delta(delta)
+        response = await self._client.chat.completions.create(
+            model=self._model, messages=self._conversation.messages
+        )
+        message = response.choices[0].message
+        content = message.content or ""
+        self._conversation.add_own_turn(content)
+        self._last_seen = round - 1
+        log_decision(
+            self.name,
+            "respond",
+            round=round,
+            saw=[e.author for e in delta],
+            output=content,
+            reasoning=_reasoning(message),
+        )
+        return content
+
+
+class Captain:
+    """The leader. ``judge`` detects consensus and locates disagreement each round; it does
+    NOT decide correctness. ``select`` picks one specialist's answer to return verbatim —
+    both coroutines. The captain acts after the round's specialists, so its cursor advances
+    to the current round (it sees this round's entries), unlike a specialist.
+    """
+
+    def __init__(
+        self,
+        *,
+        spec: AgentSpec,
+        roster: list[AgentSpec],
+        client: openai.AsyncOpenAI,
+        model: str,
+        user_query: str,
+    ) -> None:
+        _require_async_client(client)
+        self.name = spec.name
+        self._client = client
+        self._model = model
+        self._conversation = Conversation(
+            system=captain_system_prompt(spec, roster), user_query=user_query
+        )
+        self._last_seen = 0
+
+    async def judge(self, board: Scratchpad, *, round: int) -> Conclusion:
+        delta = board.delta(for_author=self.name, since_round=self._last_seen)
+        if delta:
+            self._conversation.add_delta(delta)
+        self._last_seen = round
+        try:
+            response = await self._client.chat.completions.create(
+                model=self._model,
+                messages=self._conversation.messages,
+                tools=[CONCLUDE_TOOL],
+                tool_choice=_FORCE_CONCLUDE,
+            )
+            message = response.choices[0].message
+        except openai.BadRequestError:
+            # The model answered in prose instead of calling the tool. Don't crash the
+            # run — keep debating (the conversation is left clean for a retry next round).
+            log_decision(
+                self.name,
+                "judge",
+                round=round,
+                fallback=True,
+                consensus=False,
+                direction=_FALLBACK_DIRECTION,
+            )
+            return Conclusion(consensus=False, direction=_FALLBACK_DIRECTION)
+        self._conversation.add_assistant_message(message.model_dump(exclude_none=True))
+        if message.tool_calls:
+            self._conversation.add_tool_result(message.tool_calls[0].id, _CONCLUDE_ACK)
+        conclusion = _interpret_conclusion(message)
+        log_decision(
+            self.name,
+            "judge",
+            round=round,
+            saw=[e.author for e in delta],
+            consensus=conclusion.consensus,
+            direction=conclusion.direction,
+            reasoning=_reasoning(message),
+            fallback=False,
+        )
+        return conclusion
+
+    async def select(self, candidates: list[str]) -> int:
+        """Choose the best specialist answer by number (0-based) — never rewrite it.
+
+        The captain only selects from existing answers, so it cannot corrupt the text or
+        re-derive a wrong one; the prompt tells it to follow the specialists' majority.
+        """
+        numbered = "\n\n".join(f"[{i + 1}]\n{c}" for i, c in enumerate(candidates))
+        self._conversation.add_user_message(f"{_SELECT_INSTRUCTION}\n\n{numbered}")
+        response = await self._client.chat.completions.create(
+            model=self._model, messages=self._conversation.messages
+        )
+        message = response.choices[0].message
+        index = _parse_choice(message.content or "", len(candidates))
+        log_decision(
+            self.name,
+            "select",
+            chosen=index + 1,
+            raw=message.content or "",
+            reasoning=_reasoning(message),
+        )
+        return index
+
+
+def _interpret_conclusion(message: object) -> Conclusion:
+    """Turn the captain's reply into a Conclusion, tolerating a missing tool call.
+
+    If the model skipped the `conclude` tool (no message, or no tool_calls), default to
+    no-consensus with a nudge so the debate continues instead of crashing."""
+    tool_calls = getattr(message, "tool_calls", None)
+    if not tool_calls:
+        return Conclusion(consensus=False, direction=_FALLBACK_DIRECTION)
+    return parse_conclude(tool_calls[0].function.arguments)
+
+
+def _parse_choice(content: str, n: int) -> int:
+    """First integer in [1, n] from the captain's reply, as a 0-based index (default 0)."""
+    for token in re.findall(r"\d+", content):
+        value = int(token)
+        if 1 <= value <= n:
+            return value - 1
+    return 0
+
+
+def _reasoning(message: object) -> str:
+    """The model's reasoning text, if the backend exposes one (e.g. gpt-oss)."""
+    return (
+        getattr(message, "reasoning", None)
+        or getattr(message, "reasoning_content", None)
+        or ""
+    )
+
+
+def _require_async_client(client: object) -> None:
+    if not isinstance(client, openai.AsyncOpenAI):
+        raise TypeError(
+            "Only async OpenAI clients are supported; pass an openai.AsyncOpenAI."
+        )

openai_420-0.0.1/openai_420/conclude.py

@@ -0,0 +1,52 @@
+"""The captain's per-round control signal (PRINCIPLES Law 8, 9, 10).
+
+Each round the captain calls the ``conclude`` tool. The orchestrator branches on the
+machine-readable ``consensus`` flag and never reads prose to decide. When there is no
+consensus the captain must supply a ``direction`` for the next round; on consensus it is
+omitted. The tool never carries the answer — that is a separate, consensus-gated turn.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+
+CONCLUDE_TOOL: dict = {
+    "type": "function",
+    "function": {
+        "name": "conclude",
+        "description": (
+            "Report whether the specialists have reached consensus. If not, you MUST "
+            "give a direction to focus the next round of debate. Do not include the "
+            "final answer here."
+        ),
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "consensus": {
+                    "type": "boolean",
+                    "description": "True if the team has converged and the debate can end.",
+                },
+                "direction": {
+                    "type": "string",
+                    "description": "Required when consensus is false: where to focus next round.",
+                },
+            },
+            "required": ["consensus"],
+        },
+    },
+}
+
+
+def parse_conclude(arguments: str) -> Conclusion:
+    data = json.loads(arguments)
+    return Conclusion(
+        consensus=bool(data["consensus"]),
+        direction=data.get("direction"),
+    )
+
+
+@dataclass(frozen=True)
+class Conclusion:
+    consensus: bool
+    direction: str | None

openai_420-0.0.1/openai_420/conversation.py

@@ -0,0 +1,44 @@
+"""Each agent's incremental, cached message history (PRINCIPLES Law 6).
+
+An agent's own turns are ``assistant`` messages; everyone else's new entries arrive as
+``user`` messages carrying scratchpad JSON. Only the delta is ever appended — never the
+whole board — so the prefix stays byte-stable and fully cacheable.
+"""
+
+import json
+from dataclasses import asdict
+
+from openai_420.scratchpad import Entry
+
+
+def render_delta(entries: list[Entry]) -> str:
+    return json.dumps([asdict(e) for e in entries], indent=2)
+
+
+class Conversation:
+    def __init__(self, system: str, user_query: str) -> None:
+        self._messages: list[dict] = [
+            {"role": "system", "content": system},
+            {"role": "user", "content": user_query},
+        ]
+
+    @property
+    def messages(self) -> list[dict]:
+        return list(self._messages)
+
+    def add_own_turn(self, content: str) -> None:
+        self._messages.append({"role": "assistant", "content": content})
+
+    def add_user_message(self, content: str) -> None:
+        self._messages.append({"role": "user", "content": content})
+
+    def add_delta(self, entries: list[Entry]) -> None:
+        self.add_user_message(render_delta(entries))
+
+    def add_assistant_message(self, message: dict) -> None:
+        self._messages.append(message)
+
+    def add_tool_result(self, tool_call_id: str, content: str) -> None:
+        self._messages.append(
+            {"role": "tool", "tool_call_id": tool_call_id, "content": content}
+        )

openai_420-0.0.1/openai_420/orchestrators/parallel_consensus.py

@@ -0,0 +1,92 @@
+"""ParallelConsensusOrchestrator — the v1 control loop (PRINCIPLES Law 1, 2, 3, 8).
+
+Each round: dispatch every specialist in parallel (Law 3), record their answers on the
+board the orchestrator owns (Law 1), then let the captain judge consensus (Law 8). On
+consensus the captain answers (Law 10); otherwise its direction is recorded (Law 9) and
+the next round begins. ``max_rounds`` is the backstop.
+
+This is program logic only (Law 2): it schedules and records, but never builds a prompt,
+calls a model, or reads prose to decide — it branches on the captain's boolean flag.
+
+Many orchestrator variants will live beside this one and old ones are never deleted, so
+the name states its mechanism: parallel specialists + captain-judged consensus.
+"""
+
+from __future__ import annotations
+
+import asyncio
+
+import openai
+
+from openai_420.agents import Captain, Specialist, extract_answer
+from openai_420.roster import CAPTAIN, SPECIALISTS, AgentSpec
+from openai_420.scratchpad import Scratchpad
+from openai_420.trace import log_decision
+
+DEFAULT_MAX_ROUNDS = 3
+
+
+class ParallelConsensusOrchestrator:
+    def __init__(
+        self,
+        *,
+        client: openai.AsyncOpenAI,
+        model: str,
+        specialist_specs: list[AgentSpec] = SPECIALISTS,
+        captain_spec: AgentSpec = CAPTAIN,
+        max_rounds: int = DEFAULT_MAX_ROUNDS,
+    ) -> None:
+        self._client = client
+        self._model = model
+        self._specialist_specs = specialist_specs
+        self._captain_spec = captain_spec
+        self._max_rounds = max_rounds
+
+    async def run(self, user_query: str) -> str:
+        roster = [*self._specialist_specs, self._captain_spec]
+        specialists = [
+            Specialist(
+                spec=spec,
+                roster=roster,
+                client=self._client,
+                model=self._model,
+                user_query=user_query,
+            )
+            for spec in self._specialist_specs
+        ]
+        captain = Captain(
+            spec=self._captain_spec,
+            roster=roster,
+            client=self._client,
+            model=self._model,
+            user_query=user_query,
+        )
+        board = Scratchpad()
+
+        for current in range(1, self._max_rounds + 1):
+            log_decision("orchestrator", "round_start", round=current)
+            answers = await asyncio.gather(
+                *(s.respond(board, round=current) for s in specialists)
+            )
+            for specialist, answer in zip(specialists, answers):
+                board.append(
+                    round=current, author=specialist.name, kind="answer", content=answer
+                )
+
+            conclusion = await captain.judge(board, round=current)
+            if conclusion.consensus:
+                log_decision(
+                    "orchestrator", "terminate", reason="consensus", round=current
+                )
+                return extract_answer(answers[await captain.select(list(answers))])
+            board.append(
+                round=current,
+                author=captain.name,
+                kind="direction",
+                content=conclusion.direction or "",
+            )
+
+        log_decision(
+            "orchestrator", "terminate", reason="max_rounds", round=self._max_rounds
+        )
+        return answers[await captain.select(list(answers))]

openai_420-0.0.1/openai_420/roster.py

@@ -0,0 +1,233 @@
+"""The roster and the agents' system prompts (PRINCIPLES Law 5, 11).
+
+Diversity comes from genuinely different EPISTEMOLOGIES (standards of what counts as a
+justified answer), not personas — see `docs/epistemology-research.md`. Every agent carries a
+short ``role`` tag (shown to teammates) and a full ``disposition`` (its own system prompt).
+Swap the team via ``GROUPS``; the orchestrator takes the specialist list as a parameter.
+"""
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class AgentSpec:
+    """Defined first because the roster constants below instantiate it at import time
+    (the one deviation from the docstring→imports→constants→functions→classes order)."""
+
+    name: str
+    role: str
+    disposition: str = ""
+
+
+ANSWER_MARKER = "---ANSWER---"
+
+# ── The 12 epistemology agents (distilled in docs/epistemology-research.md) ──────────────
+EVIDENTIALIST = AgentSpec(
+    "Iris",
+    "Evidentialist — grounds every claim in what the input actually gives",
+    "You first audit what is actually given — data, stated conditions, explicit assertions — "
+    "before answering, and proportion each claim to how directly the input supports it. You "
+    "do not import background knowledge or intuition without checking whether the input "
+    "already settles the matter. When the input is sufficient you answer confidently and cite "
+    "the specific evidence; when it is insufficient you say so and hedge. You flag any step "
+    "that moves beyond what the input licenses, and prefer a narrower grounded answer to a "
+    "broader one that outstrips the evidence.",
+)
+RATIONALIST = AgentSpec(
+    "Theo",
+    "Rationalist — accepts only what follows necessarily from principles",
+    "Before accepting any claim, identify the principles or definitions it must follow from. "
+    "Is it derived or merely asserted? If asserted, is it self-evident — would denying it be a "
+    "contradiction? If derived, is every inferential step valid with no unstated premises? "
+    "Evaluate by tracing the logical genealogy, not by how well it matches examples or "
+    "consensus. When underspecified, clarify definitions first. Prefer an answer that is less "
+    "comprehensive but logically secure, and flag any step that jumps without a bridging "
+    "principle.",
+)
+COHERENTIST = AgentSpec(
+    "Cora",
+    "Coherentist — maximizes fit with the whole web of claims",
+    "Treat the problem as embedded in a web of other claims and constraints. Before settling, "
+    "ask what else already accepted bears on this, and whether the candidate answer fits "
+    "smoothly or forces revisions elsewhere. Prefer the answer that leaves the whole most "
+    "consistent and integrated; treat a conflict as a diagnostic that something must give, and "
+    "ask which revision is cheapest. An answer that dissolves several existing tensions beats "
+    "one merely correct in isolation.",
+)
+FALSIFICATIONIST = AgentSpec(
+    "Pia",
+    "Falsificationist — keeps only what survives refutation",
+    "Convert your best answer into its sharpest, most committed, refutable form — vague hedges "
+    "are placeholders, not answers. Then attack it: construct the strongest objection or "
+    "counterexample and test the claim against it. If it survives unmodified, report it as "
+    "tentatively corroborated and state exactly what would overturn it; if you must patch it, "
+    "treat the patch as a liability. Never treat agreement as justification — only the absence "
+    "of successful refutation.",
+)
+ELENCHTIC = AgentSpec(
+    "Sol",
+    "Elenctic Examiner — tests claims against their own internal commitments",
+    "Take the central assertion as a hypothesis to be tested, not a foundation. Construct the "
+    "most damaging counterexample or internal inconsistency you can; if it survives, test "
+    "again from another angle. Track every commitment the reasoning has established and check "
+    "each new step for consistency with it. If a contradiction appears, surface it explicitly "
+    "and revise. Prefer exposing a genuine unresolved tension to a smooth but untested answer; "
+    "if no consistent answer survives, report the aporia honestly.",
+)
+UPDATER = AgentSpec(
+    "Bea",
+    "Calibrated Updater — reasons in calibrated probabilities",
+    "Make your uncertainty explicit and quantified before concluding. Identify the competing "
+    "hypotheses (including 'none of these'), assign each a prior, then ask how probable the "
+    "available information would be under each — update in proportion to those likelihood "
+    "ratios. Report conclusions as confidence tiers, not bare assertions, and propagate "
+    "uncertainty through multi-step reasoning. Flag when a conclusion is prior-dominated. Treat "
+    "false precision as a defect even when the central estimate is right; name the evidence "
+    "that would most change your mind.",
+)
+DISCRIMINATOR = AgentSpec(
+    "Hugo",
+    "Hypothesis Discriminator — judges by comparative evidential force",
+    "Treat every problem as comparative — never evaluate a claim in isolation; require at least "
+    "one serious rival. Ask whether the evidence actually distinguishes the alternatives and by "
+    "how much; treat evidence equally probable under all hypotheses as inert. Penalize "
+    "complexity: when two fit equally, prefer fewer assumptions. Heavily discount any "
+    "hypothesis constructed after the fact to fit the data. Report comparative verdicts and "
+    "flag when the leader wins only because the comparison set was narrow.",
+)
+PRAGMATIST = AgentSpec(
+    "June",
+    "Pragmatist — judges by what resolves the situation in practice",
+    "You first identify the specific indeterminate situation — the concrete blockage, gap, or "
+    "tension — that makes an answer necessary, and begin from the practical question: what "
+    "difference will this answer make? For every candidate, trace the claim to the observable "
+    "differences its being correct would produce. You rank answers by fitness for the actual "
+    "purpose, not elegance or precedent, and ask: if someone acted on this, would the situation "
+    "be resolved or would new problems arise? You collapse distinctions that make no practical "
+    "difference, biased toward actionability over comprehensiveness.",
+)
+HERMENEUT = AgentSpec(
+    "Gabe",
+    "Hermeneutic Interpreter — reads each part through the whole and the intent",
+    "Read the request as a text whose meaning isn't self-evident. Grasp the whole first — the "
+    "governing intent and purpose — then check each part against it; when a part resists, "
+    "revise your reading of the whole and re-examine, cycling until all parts cohere. Apply "
+    "charity: prefer the reading that attributes the most rationality. Work three layers — the "
+    "literal request, the domain conventions, and the actual purpose the answer must serve — "
+    "and if they conflict, name the conflict rather than silently picking one. Literal "
+    "compliance is not correctness.",
+)
+SYNTHESIZER = AgentSpec(
+    "Dane",
+    "Dialectical Synthesizer — integrates a position with its strongest opposite",
+    "Steelman the position and the truth it captures, then construct its strongest opposing "
+    "view and what the first fails to account for. Diagnose the shared assumption that makes "
+    "them conflict, and propose a position at a higher level that preserves the partial truth "
+    "of both — not by averaging but by reframing so each appears as a one-sided view of a "
+    "fuller whole. The test is whether your synthesis explains why each side seemed compelling; "
+    "if no genuine synthesis exists, report the contradiction and what would have to change.",
+)
+UNMASKER = AgentSpec(
+    "Max",
+    "Unmasker — questions the framing and what it makes invisible",
+    "Treat the question, its framing, and its criteria as objects of analysis before treating "
+    "them as instructions. Ask what assumptions must already be in place for this to be "
+    "well-formed, whose interests the framing serves, and what it leaves unnamed — the absent "
+    "term often carries the most weight. Assess whether the stated criteria are themselves "
+    "contestable. Surface the latent beneath the manifest: naturalized constraints, foreclosed "
+    "options. A response is deficient if it optimizes within the frame without questioning it — "
+    "but still give a direct answer at the level requested.",
+)
+VERIFICATIONIST = AgentSpec(
+    "Ada",
+    "Verificationist — dissolves claims that specify no verification conditions",
+    "Apply a two-part test to every claim: is it analytic (true by the definitions and logic "
+    "in play), or synthetic (asserting how things are, with specific observable conditions that "
+    "would confirm or disconfirm it)? Claims passing neither you don't call true or false — you "
+    "flag them as needing clarification and ask what work they are doing. Make your own claims' "
+    "verification conditions explicit, and treat terminological precision as a genuine epistemic "
+    "task. Flag any claim that resists both tests as a category confusion — it looks factual but "
+    "functions as a preference or directive.",
+)
+
+# The original task-adjacent roster (the 37% reference baseline).
+_HARPER = AgentSpec("Harper", "research, fact-checking, and supplying evidence")
+_BENJAMIN = AgentSpec(
+    "Benjamin", "logic, math, and code — verify reasoning and calculations"
+)
+_LUCAS = AgentSpec("Lucas", "divergent thinking — surface alternatives and blind spots")
+
+CAPTAIN = AgentSpec(
+    name="Captain",
+    role="detects consensus, locates disagreement, and selects the final answer",
+)
+
+# Swappable teams. The eval harness selects one by name; the orchestrator takes the list.
+GROUPS: dict[str, list[AgentSpec]] = {
+    "roles": [_HARPER, _BENJAMIN, _LUCAS],
+    "A": [EVIDENTIALIST, RATIONALIST, PRAGMATIST],  # Minimal Trident
+    "B": [
+        EVIDENTIALIST,
+        FALSIFICATIONIST,
+        UPDATER,
+        HERMENEUT,
+        UNMASKER,
+    ],  # Stress-Test Quintet
+    "C": [
+        RATIONALIST,
+        COHERENTIST,
+        FALSIFICATIONIST,
+        SYNTHESIZER,
+        UPDATER,
+    ],  # Logical Quintet
+}
+
+SPECIALISTS: list[AgentSpec] = GROUPS["roles"]  # default team
+
+
+def specialist_system_prompt(spec: AgentSpec, roster: list[AgentSpec]) -> str:
+    return (
+        f"You are {spec.name}, one of several specialists collaborating to answer a "
+        f"user's request. Each teammate judges answers by a different standard; yours is:\n\n"
+        f"{spec.disposition or spec.role}\n\n"
+        f"The team:\n{_roster_block(roster)}\n\n"
+        "How you work:\n"
+        "- The user's request is the first message. Each later round you are shown your "
+        "teammates' latest answers AND their reasoning, plus the captain's notes on where "
+        "you disagree, as JSON.\n"
+        "- Later rounds: focus on the disputed points. Read your teammates' REASONING and "
+        "weigh it against yours BY YOUR OWN STANDARD — adopt theirs if it is better "
+        "justified; keep yours only if you can defend it. Converge on the best-justified "
+        "answer, not the majority one.\n"
+        "- Output format EVERY round: first lay out your reasoning clearly and completely "
+        f"(so teammates can weigh it), then a line containing exactly `{ANSWER_MARKER}`, "
+        "then the finished deliverable itself in the language and format the user "
+        "requested — and nothing after it."
+    )
+
+
+def captain_system_prompt(spec: AgentSpec, roster: list[AgentSpec]) -> str:
+    return (
+        f"You are {spec.name}, leading several specialists to answer a user's request.\n"
+        "You do NOT decide which answer is correct — you are not the authority on the "
+        "answer. Your job is to detect agreement and locate disagreement so the "
+        "specialists can resolve it themselves.\n\n"
+        f"The team:\n{_roster_block(roster)}\n\n"
+        "How you work:\n"
+        "- Each round you see the specialists' latest answers as JSON. Call the `conclude` "
+        "tool:\n"
+        "  - consensus=true when the specialists substantively agree (differences in "
+        "wording or style do NOT block consensus).\n"
+        "  - consensus=false otherwise. In `direction`, name the SPECIFIC points where "
+        "they differ, neutrally and concretely (e.g. 'they disagree on X: one says A, "
+        "another says B'). Do NOT say which is right — just point to the disputed point "
+        "and ask them to re-examine it.\n"
+        "- Never assert facts or supply the answer yourself. If you are tempted to give "
+        "the answer, describe the disagreement instead and let the specialists settle it.\n"
+        "- When later asked to choose the final answer, pick the version the majority of "
+        "specialists agree on, verbatim — never rewrite or merge."
+    )
+
+
+def _roster_block(roster: list[AgentSpec]) -> str:
+    return "\n".join(f"- {member.name}: {member.role}" for member in roster)

openai_420-0.0.1/openai_420/scratchpad.py

@@ -0,0 +1,39 @@
+"""The shared scratchpad: the one board the orchestrator owns (PRINCIPLES Law 1, 4, 11).
+
+An append-only log of debate entries. Every entry has the same shape
+``{round, author, kind, content}`` (Law 11). The orchestrator owns it; agents never
+mutate it directly — they return text and the orchestrator records it here.
+"""
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Entry:
+    round: int
+    author: str
+    kind: str  # "answer" (a specialist) or "direction" (the captain)
+    content: str
+
+
+class Scratchpad:
+    def __init__(self) -> None:
+        self._entries: list[Entry] = []
+
+    @property
+    def entries(self) -> list[Entry]:
+        return list(self._entries)
+
+    def append(self, *, round: int, author: str, kind: str, content: str) -> Entry:
+        entry = Entry(round=round, author=author, kind=kind, content=content)
+        self._entries.append(entry)
+        return entry
+
+    def delta(self, *, for_author: str, since_round: int) -> list[Entry]:
+        """Entries this agent has not yet seen: authored by others, after ``since_round``.
+
+        This is what the orchestrator injects as the agent's next ``user`` turn (Law 6).
+        """
+        return [
+            e for e in self._entries if e.round > since_round and e.author != for_author
+        ]

openai_420-0.0.1/openai_420/trace.py

@@ -0,0 +1,17 @@
+"""Decision-point logging for the orchestration (debug + optimization aid).
+
+Every agent decision (a specialist's response, the captain's judgement, its final answer)
+and every orchestrator control step emits one structured ``DECISION`` record. Experiments
+attach a handler to the ``openai_420`` logger to capture a full trace per run, so we can see
+what each agent saw, reasoned, and produced — and pinpoint which decision is faulty.
+"""
+
+import json
+import logging
+
+logger = logging.getLogger("openai_420")
+
+
+def log_decision(agent: str, event: str, **fields) -> None:
+    payload = {"agent": agent, "event": event, **fields}
+    logger.info("DECISION %s", json.dumps(payload, ensure_ascii=False, default=str))

openai_420-0.0.1/pyproject.toml

@@ -0,0 +1,15 @@
+[project]
+authors = [{ name = "Allen Chou", email = "f1470891079@gmail.com" }]
+dependencies = ["openai"]
+description = "Grok 4.20's inference-time multi-agent chatroom, rebuilt from scratch — specialist agents debate via tool calls, a captain synthesizes."
+license = "Apache-2.0 license"
+name = "openai-420"
+requires-python = ">=3.11,<4"
+version = "0.0.1"
+
+[dependency-groups]
+dev = ["black", "isort", "pytest", "pytest-asyncio", "ruff"]
+
+[build-system]
+build-backend = "poetry.core.masonry.api"
+requires = ["poetry-core>=2.0.0,<3.0.0"]