opus-orchestrator-ai/CODE_REVIEW.md

Opus Orchestrator - Code Review

This document outlines the findings of a code review performed on the opus-orchestrator-ai repository. The review focused on identifying the root cause of a language drift issue, assessing the overall architecture, and suggesting improvements for stability and correctness.

1. Key Findings

1.1. Critical Bug: Incorrect MiniMax API Invocation

• Issue: The primary cause of the language drift (model responding in Chinese) was identified in opus_orchestrator/utils/llm.py. The LLMClient was sending the system_prompt as part of the messages array when calling the MiniMax API via its Anthropic-compatible endpoint.
• Root Cause: The Anthropic API specification requires the system prompt to be a top-level field named system in the request payload, not a message with a system role. This incorrect format caused the MiniMax model to ignore the system prompt, including the critical instruction to respond only in English.
• Impact: High. This bug directly led to the reported failure mode and undermined the primary language constraint mechanism.

1.2. Flawed AutoGen Critique and Revision Loop

• Issue: The iterate_chapter function in opus_orchestrator/autogen_critique.py contained a logic error that prevented chapter revisions from being applied correctly.
• Root Cause:
  1. The Writer agent was initially prompted to create a revision plan instead of rewriting the chapter.
  2. The calling code in iterate_chapter attempted to initiate a new multi-agent chat to perform the revision, which was inefficient and did not correctly extract the revised text from the Writer agent's output.
• Impact: High. The iterative critique process, a key feature, was non-functional. Chapters would not be improved based on feedback, regardless of the critique score.

1.3. Insufficient Language Enforcement

• Issue: While a language constraint was present in LLMClient, it was not consistently applied or reinforced across all agent layers.
• Impact: Medium. This lack of defense-in-depth meant that the single point of failure in the LLMClient was sufficient to cause the language drift. Explicitly instructing every agent to use English provides resilience against future integration issues.

2. Architectural Observations

• Good Separation of Concerns: The project demonstrates a good high-level structure. The separation of crews, agents, langgraph_workflow, and utils is logical.
• Multiple Orchestration Strategies: The codebase supports LangGraph, CrewAI, and custom agent loops (orchestrator.py). This provides flexibility but also increases complexity and maintenance overhead.
• Structured Output: The use of PydanticAI (pydanticai_agent.py) is a good practice for ensuring structured, validated outputs from LLM calls, reducing the risk of parsing errors.
• Configuration Management: config.py provides a centralized way to manage settings, which is effective.

3. Recommendations & Actions Taken

The following actions were taken to address the findings:

1. Fixed MiniMax API Call:

   • Modified _complete_minimax_async and _complete_minimax_sync in opus_orchestrator/utils/llm.py to pass the system prompt as a top-level field in the payload, correcting the API call format.

2. Repaired AutoGen Revision Loop:

   • Updated the Writer agent's system prompt in autogen_critique.py to instruct it to output the full, revised chapter text.
   • Rewrote the revision logic in iterate_chapter to directly call the Writer agent with the critique and extract its reply as the new chapter content.

3. Strengthened Language Enforcement:

   • Added a universal English-language constraint to BaseAgent in opus_orchestrator/agents/base.py, ensuring all standard agents inherit this rule.
   • Added the same constraint to the base prompt for OpusPydanticAgent in opus_orchestrator/pydanticai_agent.py.
   • Added explicit constraints to the Writer agent in the autogen_critique module.

This comprehensive set of fixes addresses the critical language drift bug, repairs the core feedback loop, and hardens the system against similar issues in the future.