Polaris

A runtime-native AI intelligence platform for portfolio analysis, risk assessment, strategy synthesis, and financial reporting.

What is Polaris? · Features · Architecture · Quick start · CLI · Docs

Project status

[!IMPORTANT]
Polaris is a work in progress. The platform is under active development and is not yet a stable public API, production trading system, or investment advisory product. Interfaces, schemas, workflows, and defaults may change as the architecture matures.

Polaris is recommendation-oriented. It can analyze markets and portfolios, generate reports, produce strategy and risk assessments, inspect historical runs, and run deterministic simulations. It does not place live broker orders or autonomously trade capital.

[!WARNING]
Polaris is research and decision-support software. Outputs are not financial, investment, legal, tax, or trading advice. Always verify data and decisions independently before acting.

What is Polaris?

Polaris is a Python platform for building replayable AI-assisted portfolio-management workflows. It combines typed application services, provider-based market integrations, a workflow runtime, persisted execution evidence, curated RAG, and observability into one platform-native architecture.

Polaris is designed to answer questions such as:

• What changed in market conditions since the last report?
• What does the current technical, macro, sentiment, news, portfolio, and risk picture look like?
• Why did the platform produce a recommendation or risk assessment?
• What evidence and node outputs contributed to a completed workflow run?
• How would a strategy or workflow behave under deterministic historical or simulated inputs?
• Which curated records should be used for grounded RAG-backed answers?

Feature matrix

How it works

Polaris follows an inside-out architecture. The runtime is the trunk; application services, integrations, intelligence, reporting, CLI, MCP, and future interfaces are branches.

Interface: CLI / MCP / future API
    -> WorkflowFacade
    -> WorkflowBootstrap + Dishka request scope
    -> RuntimeEngine
    -> RuntimeNode graph
    -> RuntimeNodeOutput
    -> RuntimeContext
    -> PostgreSQL completed-run and domain persistence
    -> Curated records
    -> Qdrant / Neo4j RAG projections
    -> Reports, answers, audit, and inspection

External data enters through a strict service/provider/client boundary:

Application service
    -> provider protocol
    -> vendor-specific async client
    -> external system

This keeps vendor SDKs and transport concerns out of intelligence agents and workflow nodes. Internal platform contracts are strongly typed; dictionaries are reserved for external APIs, telemetry, persistence serialization, runtime boundaries, and transport payloads.

Why Polaris is designed this way

Portfolio-management use cases

Polaris can be used as a decision-support platform for portfolio workflows such as:

• generating a daily or intraday market and portfolio morning report;
• evaluating current portfolio risk, concentration, volatility, and drawdown context;
• combining technical, macro, sentiment, news, and portfolio evidence into strategy rationale;
• reviewing historical recommendations and completed workflow outputs;
• asking grounded RAG-backed questions over curated platform records;
• testing deterministic scenarios with fixed inputs and independently verified expected outcomes;
• monitoring providers, data quality, workflow execution, and observability signals.

Core components

Quick start

Prerequisites

• Python 3.12+
• uv for dependency management
• Docker Compose for local infrastructure
• Optional: NVIDIA GPU support for the local BGE reranker container

1. Clone and install

git clone <your-polaris-repo-url>
cd polaris
uv sync

2. Configure environment

cp .env.example .env

Edit .env and set local secrets. At minimum, local Docker services require values for:

POLARIS_POSTGRES_PASSWORD=
NEO4J_AUTH=
GRAFANA_ADMIN_PASSWORD=

Optional provider/API credentials include Alpaca, Alpha Vantage, FRED, NewsAPI, Massive, LiteLLM-backed model endpoints, and other data vendors listed in .env.example. Local web fallback uses SearXNG for discovery and Crawl4AI for content acquisition.

[!CAUTION]
Do not commit .env, API keys, passwords, authenticated database URLs, or vendor tokens.

3. Start local infrastructure

docker compose up -d postgres qdrant neo4j litellm

Optional observability and RAG support services:

docker compose up -d prometheus jaeger grafana
# Optional reranker; requires the configured local model volume/GPU environment.
docker compose up -d bge-reranker
# Optional local web-search discovery for explicit RAG web fallback.
docker compose up -d searxng

Optional RAG web fallback also requires Crawl4AI browser setup on the host:

uv run crawl4ai-setup
uv run crawl4ai-doctor
# If browser dependencies are missing:
uv run python -m playwright install --with-deps chromium

Web fallback remains disabled by default and must be enabled in .env and per request. SearXNG only performs search/discovery; Crawl4AI performs concurrent content acquisition and Markdown extraction. Returned web evidence is transient and untrusted unless explicitly curated later.

Optional Reranker Cache Pre-loading

The bge-reranker service container requires local access to the model weights to perform local cross-encoder document scoring. To bypass network throttling and prevent Docker container timeouts during initial boot, pre-load the weights into your local cache directory before launching the composition stack.

1. Download the Weights via Python (Bypasses Rate Limits)

Hugging Face heavily prioritizes its official Python huggingface_hub library and allows it to use automated multi-stream download acceleration (hf_transfer). Run this script inside your workspace terminal to pull the model down directly using your unthrottled host connection:

uv run python -c "
from huggingface_hub import snapshot_download
snapshot_download(
    repo_id='BAAI/bge-reranker-large',
    local_dir='./.bge_data',
    ignore_patterns=['*.bin', '*.msgpack', '*.h5'] # Only grab the lightweight config & .safetensors files
)
"

2. Launch the Accelerated Container

Once the .bge_data/ cache folder is populated on your host filesystem, boot the hardware-accelerated reranking service node:

docker compose up -d bge-reranker

LiteLLM is the canonical local LLM gateway. Polaris sends logical model names to LiteLLM; LiteLLM routes them to configured backends such as host Ollama. If the LiteLLM container routes to host Ollama, make Ollama container-reachable with OLLAMA_HOST=0.0.0.0:11434 or set POLARIS_LITELLM_OLLAMA_API_BASE to another reachable endpoint.

Optional Host Ollama Connectivity for LiteLLM Configuration

If your local LiteLLM container fails to reach Ollama via host.docker.internal:11434 (connection refused), it means Ollama is currently bound only to your host's local loopback interface (127.0.0.1). Inside a Docker container, 127.0.0.1 references the container itself, not your host machine.

To allow internal Docker container network loops to communicate with your host's Ollama instance permanently, configure the background system daemon to bind to all network interfaces (0.0.0.0).

On Linux and Windows WSL2 systems, Ollama's automatic lifecycle is managed by systemd as a background system service. Because system background processes bypass your standard .bashrc or profile scripts, you must configure the service directly using the steps below:

1. Open the System Service Configuration Overrides

Open the system service editor for the Ollama background daemon:

sudo systemctl edit ollama.service

(This opens a blank configuration override file inside your system's default command-line text editor, such as Nano).

2. Inject the Global Listening Environment Variable

Paste these lines directly into the empty file layout to declare the host binding rule:

[Service]
Environment="OLLAMA_HOST=0.0.0.0:11434"

If you are using Nano, save and exit by pressing Ctrl + O, hitting Enter, and then pressing Ctrl + X.

3. Reload the Daemon and Restart the Service

Instruct the operating system's initialization framework to parse the updated parameter properties and restart the active background listener:

# Reload the system orchestration configuration files
sudo systemctl daemon-reload

# Restart the background service to bind to 0.0.0.0
sudo systemctl restart ollama

4. Refresh the LiteLLM Proxy Ingestion Bridge

Once your host machine's service daemon is listening globally, force your local routing container to drop its stale connection threads and bind cleanly to the fresh host api base:

docker compose up -d litellm --force-recreate

4. Apply database migrations

uv run alembic upgrade head

5. Verify the CLI

uv run polaris --help
uv run polaris inspect config
uv run polaris workflow list

CLI usage

Morning report

uv run polaris morning-report
uv run polaris morning-report --symbol SPY

Terminal output, progress notifications, and interactive workflow control are enabled by default. Use --format when you also want a file artifact:

uv run polaris morning-report --format markdown
uv run polaris morning-report --format html
uv run polaris morning-report --format json
uv run polaris morning-report --format pdf

Workflows

uv run polaris workflow list
uv run polaris workflow describe morning_report
uv run polaris workflow run morning_report

Completed runs

uv run polaris runs list morning_report
uv run polaris runs show morning_report <execution_id>

RAG

uv run polaris rag status
uv run polaris rag ingest --source reports
uv run polaris rag process-embeddings
uv run polaris rag process-graph
uv run polaris rag ask "What changed in the latest portfolio risk assessment?"

RAG uses PostgreSQL as the canonical source, Qdrant for hybrid vector projection, Neo4j for graph projection, BGE reranking, and optional SearXNG + Crawl4AI transient web fallback depending on configuration and service availability.

Backtesting

uv run polaris backtest --help
uv run polaris backtest run --scenario path/to/scenario.yaml

Backtests run through the same production workflow runtime and swap data providers through composition. Deterministic scenarios should use fixed inputs, time, seeds, and independently derived expected outcomes.

MCP server

uv run polaris-mcp --help

The MCP server is intended for external LLM-agent hosts that need controlled access to Polaris. It is a thin transport over canonical application services, not a second RAG, persistence, or workflow implementation.

Platform-native RAG

Polaris RAG is designed around curated records rather than raw dumps.

Curated PostgreSQL records
    -> canonical RAG documents and chunks
    -> embedding and graph projection jobs
    -> Qdrant and Neo4j projections
    -> hybrid retrieval, reranking, CRAG, Self-RAG, and answer logs

Important rules:

• PostgreSQL remains authoritative.
• Qdrant and Neo4j are rebuildable projections.
• SearXNG + Crawl4AI web evidence is transient unless explicitly curated later.
• RAG documents are generated only from eligible, typed, attributable records.
• Query and answer logs are persisted for audit and inspection.

See docs/platform_rag_pipeline.md for the full architecture.

Observability

Polaris includes core observability for local development and platform operations:

Useful local endpoints when services are running:

See docs/core_telemetry_observability.md.

Development

Common checks:

uv run ruff check .
uv run ruff format .
uv run mypy . --explicit-package-bases
uv run pytest

Database validation:

uv run alembic upgrade head
uv run alembic check
uv run pytest -q tests/database/test_migrations.py

After meaningful Python architecture changes, update the local code graph:

uv run graphify update .

Documentation

Public roadmap themes

Polaris is actively evolving. Near-term public-facing work may include:

• stronger installation and sample-data workflows;
• additional deterministic backtesting scenarios;
• expanded MCP tool coverage for approved external agent hosts;
• more curated-record projection coverage;
• improved web/API interfaces;
• deeper governance, approval, and policy workflows;
• broader test coverage and release hardening.

Contributing

Contributions are welcome once the public contribution process is finalized. For now, open an issue or discussion with:

• the problem you are trying to solve;
• the workflow, service, provider, or interface involved;
• whether the change affects runtime contracts, persistence schema, RAG projections, or telemetry;
• the verification you expect to run.

Please keep changes surgical, typed, observable, and aligned with the canonical runtime and persistence boundaries.