Home

Auris

Auris is a terminal-based AI financial advisor. It combines real-time market data with conversational AI so you can analyse instruments, run financial calculations, and manage portfolios — entirely from your terminal.

You ask questions in natural language — "How volatile has AAPL been over the last six months compared to MSFT?" — and the agent answers by orchestrating 58 tools over live market data, a deterministic financial calculation engine, and your own portfolios.

🛑 Before you do anything else, read AI Disclaimer & Responsible Use. Auris is a decision-support and educational tool, not regulated financial advice — and the wiki page explains exactly what that means in practice, with examples.

🧭 Three design principles

1. The LLM never does arithmetic. Every number — ROI, Sharpe ratio, VaR, DCF, Monte Carlo paths — is computed by a pure Go calculation engine (pkg/finance) with strictly validated inputs. The model decides what to compute; the code decides the result. This eliminates numeric hallucination in the domain where it matters most.
2. Every external service is a swappable driver. LLM backends and market data providers implement narrow interfaces behind a registry, so adding a provider never touches the core.
3. Local-first and private by default. Auris runs as a single static binary, supports fully local inference via Ollama, and encrypts credentials — and optionally portfolios and chat history — at rest with Argon2id + AES-256-GCM.

📚 Wiki index

For new users

Page	What you'll find there
🚀 Using the Agent	First steps, the setup wizard, recommended first prompts, and a full portfolio-creation walkthrough.
⚠️ AI Disclaimer & Responsible Use	What Auris's numbers can and can't responsibly be used for, with good/bad practice examples.
❓ FAQ & Troubleshooting	Common questions, provider errors, and what to do when something looks stuck.

For contributors

Page	What you'll find there
🤝 Contributing	Fork, branch, commit convention, local checks, and how to open a PR.
🛠️ Building from Source	Requirements, go build, Nix, running the test suite, and how releases are built.
🧪 System Prompt Refinement	Testing and iterating on the agent's system prompt with promptlab — command reference, comparing results, strategies, and false positives to watch for.

Under the hood

Page	What you'll find there
🏛️ Architecture & Design Decisions	The ports & adapters shape of the codebase and the reasoning behind ten key design decisions.
🔒 Security & Privacy	Exactly how credentials, portfolios, and sessions are encrypted at rest, and what that protects against (and what it doesn't).
🗺️ Roadmap & Future Work	What's shipped, what's genuinely still open, and what's aspirational.

🏗️ Architecture, at a glance

Auris follows a ports & adapters (hexagonal) architecture. The two core domains — market data and AI inference — are defined as small interfaces ("ports") in pkg/market and pkg/llm; each concrete provider is an isolated driver package ("adapter") in pkg/drivers/, wired up through a static registry.

flowchart TB
    subgraph UI["Presentation"]
        TUI["pkg/tui — Bubble Tea<br/>setup wizard · agent chat · portfolios · charts"]
    end

    subgraph CORE["Application core"]
        AGENT["pkg/agent<br/>ReAct loop · 58 tools · market chain"]
        FIN["pkg/finance<br/>deterministic calculation engine"]
        PORT["pkg/portfolio<br/>FIFO lots · metrics · export"]
    end

    subgraph PORTS["Ports (interfaces)"]
        LLMIF["pkg/llm<br/><code>AIProvider</code>"]
        MKTIF["pkg/market<br/><code>ProviderAPI</code>"]
    end

    subgraph LLMDRV["LLM drivers"]
        OLLAMA["Ollama"] ~~~ GEMINI["Gemini"] ~~~ CLAUDE["Claude"] ~~~ OPENAI["OpenAI¹"] ~~~ MINIMAX["MiniMax"]
    end

    subgraph MKTDRV["Market drivers"]
        FMP["FMP<br/>(primary)"] -->|fallback| EODHD["EODHD<br/>(secondary)"]
        SIM["Simulation"]
    end

    TUI --> AGENT
    AGENT --> FIN
    AGENT --> PORT
    AGENT --> LLMIF
    AGENT --> MKTIF
    LLMIF --> LLMDRV
    MKTIF --> MKTDRV

Loading

¹ The OpenAI driver also serves any OpenAI-compatible endpoint (DeepSeek, Groq, OpenRouter, self-hosted proxies…), registered as a separate provider entry.

See Architecture & Design Decisions for the rationale behind this shape.

🔗 Elsewhere

• Repository
• README (English) · README_ES (Spanish)
• MIT License
• Open an issue

---

This wiki documents Auris as a terminal application. It doesn't replace the README's quick-start — it goes deeper on the topics the README only summarises.