How fzorri/second-opinion works
What this project is (type + purpose)
Second Opinion is a local Python CLI application that lets a user chat with many different LLM providers through a single interface, with:
• Runtime model selection (currently “26” models, configurable)
• Provider-specific adapters/wrappers (OpenAI, Anthropic, Groq, Google, etc.)
• Local persistence of conversation history (JSON on disk, per model/folder)
• A models registry/config (models.yaml) + secrets (.env)
So the architecture is best represented as:
• A client-side CLI app (no server you deploy)
• That orchestrates outbound API calls to multiple external LLM services
• And reads/writes local config + local history storage
This is not a typical “frontend/backend/database” web system; it’s a pluggable CLI orchestrator + adapters.
Read the file tree as architecture hints (what each area likely represents)
Top-level:
• secop.py → main entrypoint / CLI controller (menu, model selection, chat loop, autocheck, history mode)
• tools.py → shared utilities (formatting, IO helpers, request helpers, etc.)
• config.py → config loading / environment handling / defaults (likely .env, paths, toggles)
• models.yaml → model catalog + settings (enable/disable models, provider mapping, folders, params)
• history.py → local conversation persistence & history operations (browse, preview, merge, delete, resume)
• llm_classes/ → provider abstraction layer:
• llm_base.py → common interface/contract used by secop.py
• llm_*_base.py → provider-specific implementations (Anthropic/Google/OpenAI/Groq/etc.)
• requirements.txt → Python deps (implies runtime environment and 3rd-party HTTP SDKs)
• secop.bat → Windows convenience launcher
This tree strongly suggests a “core app” that depends on a “provider adapter layer” and a “local storage/history layer”.
Nodes to include:
• User (CLI Operator)
• Second Opinion CLI App (Python process)
• Local File System
• .env (secrets) *(even if not committed, it’s runtime-critical)*
• models.yaml (model definitions)
• history/… folders (JSON conversation logs; structure determined by model_folder in models.yaml)
• External LLM Providers (Internet)
• OpenAI API
• Anthropic API
• Google API
• Groq API
• xAI API
• DeepSeek / Fireworks / GLM / etc. (group them if needed)
• User → CLI: prompts, commands (“end”, menu selection)
• CLI → External LLM APIs: prompt/messages + model params
• External APIs → CLI: completions/responses
• CLI ↔ Local FS: read config + write/read history JSON
Goal: show the major subsystems inside the Python process and how they interact.
Recommended containers/components inside “Second Opinion CLI”:
CLI Controller / Orchestrator (secop.py)
• menu
• chat loop
• autocheck loop
• routing to history mode
Configuration & Model Registry
• models.yaml loader (often in config.py or in secop.py)
• .env secret loader (via config.py)
• Produces: “Enabled models list” + provider mapping + per-model params
LLM Provider Abstraction Layer (llm_classes/)
• LLMBase interface (llm_base.py)
• concrete providers (llm_openai_chatgpt_base.py, llm_anthropic_base.py, etc.)
• responsibility: normalize “send messages” / “get response” across vendors
History / Persistence Subsystem (history.py)
• write conversation JSON
• browse/preview/resume/merge/delete
Utilities (tools.py)
• formatting/markup rendering
• shared helpers for file IO, validation, etc.
• secop.py → Config/Registry: “load enabled models”
• secop.py → LLMBase implementations: “send conversation”
• secop.py → History subsystem: “save conversation”, “load conversation”, “merge”
• Provider implementations → External APIs (outbound HTTPS)
• History subsystem → Local disk (JSON)
Flow 1: “Start app → pick model → chat → save”
Sequence (recommended lifelines):
• User
• secop.py (controller)
• Config loader (config.py / models.yaml)
• Provider instance (LLMBase + specific implementation)
• External LLM API
• History manager (history.py)
• Local disk
Steps to show:
Flow 2: “History mode → resume conversation”
Show:
• user selects prior JSON conversation
• history loads JSON
• secop routes to provider and continues messages
Flow 3: “Autocheck option A”
Show:
• loop over enabled models in models.yaml
• attempt lightweight request per provider
• report success/failure (and potentially store diagnostics)
Architectural patterns/design principles to explicitly call out
These are visible from the structure and should be represented:
Adapter/Strategy pattern for providers
• LLMBase = stable interface
• llm_* = interchangeable strategies chosen by config
Configuration-driven composition
• models.yaml controls which models exist + parameters + storage folders.
• .env controls secrets without code changes.
Local-first persistence
• history is stored on disk as JSON, per model folder.
Single-process CLI runtime
• everything runs in one Python process; no internal network hops.
Labels directly on components:
• Python 3.10+ runtime (Conda env recommended by README)
• CLI interface (terminal)
• YAML config (models.yaml)
• Environment variables (.env from .env.template)
• JSON persistence (conversation logs)
• Outbound HTTPS to external LLM APIs
• Chat flow
• History resume (or Autocheck)