Using the Agent

🚀 Using the Agent

Before diving in: read AI Disclaimer & Responsible Use once. It's short, and it explains what Auris's answers can and can't be trusted for.

First steps

The setup wizard

On first launch, Auris runs a guided setup wizard:

1. Language — auto-detected, prompted if ambiguous.
2. Theme — 6 light/dark variants.
3. Passphrase — encrypts your API keys (and optionally portfolios/sessions) at rest. See Security & Privacy for how, and FAQ & Troubleshooting for what happens if you forget it.
4. Financial profile — 10 questions, described below.
5. Data mode — real market data (needs an API key) or simulation mode (synthetic data, zero signup).
6. Market providers — an FMP API key, optionally EODHD as a fallback.
7. AI providers — pick one or more of Ollama, Gemini, Claude, OpenAI, MiniMax, or an OpenAI-compatible endpoint, and configure each.
8. Default model — the provider/model pair used by default when you open the chat.

You can press Esc to step back through the wizard at any point if you change your mind, and re-run it later with auris -setup. On subsequent launches you're only asked for your passphrase.

If you just want to explore without committing to any API key, choose simulation mode at step 5 — every tool in this guide works against synthetic data, so it's the fastest way to get a feel for the agent before connecting real providers.

The financial profile

The 10 questions (life stage, income stability, investment goals, time horizon, how you'd react to a loss scenario, maximum acceptable loss, financial experience, investment priority, and any restrictions) aren't just onboarding friction — they're injected into every system prompt the agent sees. Two people asking the exact same question can get differently-framed answers, because the agent knows one has a 30-year horizon and high risk tolerance while the other is close to retirement and loss-averse. You can revisit and change your profile later from the menu.

How an answer gets grounded

It's worth understanding the shape of what happens after you hit enter, because it's the reason Auris's numbers can be trusted even though the thing generating the sentence around them is a language model:

sequenceDiagram
    participant You
    participant Agent as ReAct loop<br/>(pkg/agent)
    participant LLM as LLM provider
    participant Tools as Tool dispatch
    participant Engine as pkg/finance /<br/>market chain

    You->>Agent: "What's AAPL's Sharpe ratio<br/>over the last year?"
    Agent->>LLM: prompt + tool schemas
    LLM-->>Agent: "call market_get_candles(AAPL, 1y)"
    Agent->>Tools: dispatch
    Tools->>Engine: fetch candles (FMP → EODHD fallback)
    Engine-->>Agent: candle data
    Agent->>LLM: candle data + prompt
    LLM-->>Agent: "call calculate_sharpe(returns, rf)"
    Agent->>Tools: dispatch
    Tools->>Engine: CalcSharpe(...)
    Engine-->>Agent: exact numeric result
    Agent->>LLM: numeric result
    LLM-->>You: streamed, formatted answer

Loading

The model never computes the Sharpe ratio itself — it recognises that a Sharpe ratio question needs candle data, then a calculation, and calls the two tools in order. Up to 10 tool-calling rounds (maxLoopIterations) are available per message before the loop gives up, which is normally far more than a real question needs. Responses stream token-by-token as they're generated — you don't wait for the whole answer to appear at once, including while tool calls are happening in the background.

Recommended first prompts

A good first session mixes a market-research question, a calculation, and (if you've created one) a portfolio question — enough to see the different tool categories in action.

📈 Market research

• "How volatile has AAPL been over the last six months compared to MSFT?"
• "Show me a price chart for BKT.MC over the last year." — renders a candlestick + SMA20 chart directly in the chat.
• "What's Tesla's P/E ratio and dividend yield right now?"
• "Search for instruments matching 'Iberdrola'."

🧮 Valuation & risk

• "Run a DCF on MSFT assuming 8% revenue growth and a 10% discount rate."
• "What's the Sharpe and Sortino ratio for NVDA over the last two years?"
• "Stress-test a $50,000 position in QQQ against a 20% market crash."
• "Run a Monte Carlo simulation for a $10,000 investment in the S&P 500 over 10 years."

💼 Portfolio

• "Create a portfolio called 'Retirement' with $10,000 starting cash in USD."
• "Add 10 shares of AAPL at $150, bought on 2024-03-01."
• "What's my portfolio's concentration risk?" — computes the Herfindahl-Hirschman Index and tells you whether you're concentrated, moderate, or diversified.
• "Suggest a rebalance toward my target allocation."
• "How does my portfolio compare to the S&P 500 over the last year?" — alpha/beta benchmark comparison.

📰 News

• "What's the latest news on the semiconductor sector?"

Every one of these routes through the grounding flow above — none of these numbers come from the model's training data.

Creating and growing a portfolio

There are two equally valid ways to build a portfolio, and both write to the exact same files, so you can freely mix them within a single portfolio:

• The TUI wizard: from the main menu, open the portfolio menu → Create portfolio → walk through name, description, starting cash, currency, and an optional default AI provider/model for that portfolio specifically.
• Conversationally, through the agent: just ask it to create one and add to it, as in the prompts above.

A typical walkthrough, entirely conversational:

1. "Create a portfolio called 'Growth' with $5,000 starting cash in EUR."
2. "Add 5 shares of ASML at €650, bought last month." — recorded as a FIFO lot; Auris tracks 6 transaction types under the hood (buy, sell, dividend, deposit, withdrawal, and adjustment, kept distinct for auditability).
3. "I received a €12 dividend from ASML today." — recorded as a dividend transaction, feeding into realised P&L.
4. "Set my target allocation to 60% ASML, 40% cash."
5. "Suggest a rebalance." — compares current weights to the target and proposes buy/sell operations within a drift tolerance. It only ever suggests — nothing executes automatically.
6. "Sell 2 shares of ASML." — consumes the oldest lots first (FIFO), so cost basis stays accurate for tax purposes.
7. "What's my realised and unrealised P&L, and how does it compare to the S&P 500?"
8. "What's my tax P&L for this year, split by short-term and long-term gains?"

Watchlists work the same conversational way for instruments you want to track without owning, and every portfolio can be exported to JSON (full fidelity, re-importable) or CSV.

A few tips

• Toggle between the main menu and the agent chat with Shift+Tab.
• Conversations persist as sessions — closing and reopening Auris doesn't lose your chat history.
• If something looks wrong with a tool call, rerun with auris -debug <path> to append per-iteration agent diagnostics to a file for troubleshooting (off by default, for privacy).
• Storage encryption for portfolios and chat sessions is on by default for new setups; toggle it from the menu (/encryption) at any time.

---

Once you're comfortable with the basics, Architecture & Design Decisions explains the reasoning behind the tool/market-chain design in more depth, and AI Disclaimer & Responsible Use is worth a second read once you're using Auris for real decisions rather than just exploring.