[Meta] Roadmap to a working host-native Ollama development setup

Purpose

Track the work required to make TradingAgents a dependable development system using a Python virtual environment and an existing Ollama server. Docker is intentionally deferred to the production-packaging phase; it is not required for normal development.

The current checkout is v0.2.4-era code with local, uncommitted Ollama changes, while upstream main has advanced to v0.3.1. Preserve and port the useful local work rather than merging it blindly.

Ordered work plan

1. Establish the development baseline

• Preserve the current uncommitted Ollama changes and generated reports outside the working commit.
• Move the working branch onto the current upstream main baseline.
• Use Python 3.12 in a virtual environment.
• Install the project with development dependencies.
• Get the full test suite and lint checks passing in a clean checkout.
• Add/confirm a documented clean-install and smoke-test path.

Related: #970, #1222.

2. Make remote Ollama a first-class development provider

• Configure OLLAMA_BASE_URL for a local or remote Ollama server.
• Verify the endpoint from the same host/process that runs TradingAgents.
• Make model discovery work against the configured remote endpoint, not only localhost.
• Support explicit custom model IDs and current Ollama cloud-model IDs.
• Add startup preflight showing the resolved endpoint and selected models.
• Verify structured output/tool calling for the chosen quick and deep models.
• Add timeouts, retry behavior, and a conservative configurable concurrency limit.
• Run a minimal end-to-end analysis against the real Ollama server.

Related: #605, #621.

3. Harden market and external-data access

• Verify yfinance connectivity and document proxy/network requirements.
• Make Reddit and StockTwits failures non-fatal and visible in the report.
• Handle rate limiting/backoff without making a run appear hung.
• Validate ticker normalization and exchange-qualified symbols.
• Ensure historical runs never include data newer than the requested trade date.
• Detect stale/missing market data and stop or warn explicitly.

Related: #968, #1193, #1201, #1023, #1220.

4. Make runs reproducible and usable without a person at the terminal

• Add a non-interactive configuration path for provider, models, ticker, date, analysts, and research depth.
• Add environment/config controls for report-save and report-display prompts.
• Record the exact provider, model IDs, temperatures/reasoning settings, data windows, vendors, and tool calls.
• Include data-source provenance in analyst and consolidated reports.
• Verify checkpoint, memory, and report directories persist across runs.
• Document expected non-determinism and provide reproducibility controls where supported.

Related: #1133, #1197, #1239.

5. Validate decision correctness before treating output as trustworthy

• Ensure an unparseable rating cannot silently become Hold.
• Prevent reflection from settling before the configured holding window.
• Pass market context needed to justify Trader entry/stop/target values.
• Add an explicit, typed portfolio-context contract.
• Add deterministic cross-field validation for decision outputs.
• Surface missing context and inconsistent outputs as warnings or review states.

Related: #1166, #1167, #1168, #1169, #1170.

6. Select and implement a proper memory system

The current project has no dedicated memory/retrieval subsystem; the wiki is the only intended persistent knowledge source for now. This phase should be designed after the baseline run works.

• Define memory requirements: run history, reflections, research lessons, source citations, timestamps, ticker/instrument scope, and deletion/retention.
• Compare local-first options, including a structured store plus full-text/vector retrieval.
• Choose the smallest system that supports reliable local development and can later be promoted to production.
• Define memory boundaries so stale or cross-ticker information cannot contaminate a run.
• Add retrieval/evaluation tests, provenance, and reset/export tooling.
• Implement memory injection into the appropriate agents only after retrieval quality is verified.

7. Add wiki ingestion and grounding

• Define the wiki snapshot/update contract and versioning.
• Add an explicit import/update command once the data-copy procedure is available.
• Parse, chunk, index, and retrieve wiki content with source/version citations.
• Apply temporal filtering where historical analysis requires it.
• Test behavior for stale, missing, and conflicting wiki content.
• Keep wiki knowledge separate from run/reflection memory.

8. Package for production later

• Decide whether the production target is scheduled CLI jobs, a worker service, or an API.
• Add Docker only after the host-native workflow is stable.
• Add health checks, persistent storage, secret handling, resource limits, logs, metrics, and alerting.
• Add a scheduler/queue and explicit run concurrency controls.
• Document backup and recovery for reports, checkpoints, memory, and wiki indexes.

Working-phase definition of done

• A clean Python 3.12 virtual environment installs successfully.
• Tests and lint pass.
• A configured remote Ollama server completes a minimal analysis.
• Reports, checkpoints, and run metadata persist and are reproducible enough to audit.
• The run can execute without interactive prompts.
• Historical analyses do not use future data.
• Missing external data or model capabilities produce visible warnings rather than plausible-looking fabricated output.
• The memory and wiki systems have explicit boundaries and provenance.

This issue is a tracker; implementation should happen in focused child issues or pull requests.