A local Windows desktop financial BI platform for source-grounded research, market analysis, and Word, Excel, and PowerPoint generation.
Demo · SPD-RAG paper · Architecture · Quick start · Contributing
Important
AIris is a research prototype that runs locally and calls third-party APIs configured by the user. Some workflows send document content, prompts, or generated artifacts to paid external services. See External services.
The source is available under the PolyForm Noncommercial License 1.0.0: noncommercial use is permitted, commercial use is not. See License.
Full demo on YouTube (Turkish audio). The example workflow below is an English written walkthrough of the same capabilities.
AIris is a financial BI platform for teams whose evidence is scattered across reports, contracts, filings, and market data. A user uploads those documents, asks questions in English or Turkish, and can receive streamed answers with source cards, retrieved table or figure images, charts, and finished Office files.
A coordinator agent owns each conversation and calls specialist agents as tools. Retrieval and provider tools supply evidence from the user's documents and from market, macroeconomic, and web sources. For questions that must cover every selected document, the user can enable SPD-RAG, a per-document retrieval method published in arXiv:2603.08329 and implemented in this repository.
- Document Q&A with source artifacts. Hybrid vector and BM25 retrieval with Cohere reranking; responses include source cards and can include supporting table or figure images when retrieved.
- Document-parallel cross-document research. SPD-RAG assigns one bounded retrieval worker to each selected document, then merges findings through token-budgeted recursive synthesis.
- Market and macro data. Marketstack end-of-day data and Turkish Central Bank EVDS series, discovered semantically and retrieved by date range.
- Charts and Office deliverables. Interactive Plotly charts and Word, Excel, or PowerPoint files generated from sandboxed code and returned as attachments.
- Financial news workspace. RSS stories clustered and summarized by an LLM, with a dedicated agent for questions about a story.
- Supporting workspaces. A market dashboard and deterministic financial calculators.
- Live progress. Tool calls, specialist steps, and SPD-RAG document progress are streamed to the desktop client over Server-Sent Events.
AIris is a research and competition project intended for local evaluation and extension. It has not been audited for production trading, regulated financial workflows, multi-user deployment, or unattended operation. Generated analysis may omit context or draw unsupported inferences and should be verified against the displayed sources. Source cards expose artifacts returned by tools; they do not guarantee statement-level citation coverage. Outputs are framed as analysis, not investment advice.
- Windows with PowerShell
- Python 3.11 or newer
- Node.js 22.12.0 or newer
- uv
- API keys for the providers listed under Backend startup configuration
git clone https://github.com/NebulAICompany/AIris.git
Set-Location AIris
uv sync --locked
.\.venv\Scripts\Activate.ps1
Copy-Item .env.example .env
# Edit .env and add your keys.
Set-Location frontend
npm ci
Set-Location ..The backend creates its provider clients at startup, so these values must be present in .env before it will start:
| Variable | Used for |
|---|---|
ANTHROPIC_API_KEY |
Coordinator and specialist agents |
OPENAI_API_KEY |
Moderation, SPD-RAG, summarization, news, vision |
COHERE_API_KEY |
Embeddings and reranking |
TAVILY_API_KEY |
Web search |
QWEN_API_KEY |
Optional alternative coordinator client; unused unless selected in code |
AZURE_DOCUMENT_INTELLIGENCE_ENDPOINT |
Document parsing service endpoint |
PDF and DOCX ingestion additionally requires AZURE_DOCUMENT_INTELLIGENCE_KEY. The example workflows require the relevant feature keys listed under External services. .env is ignored by git; never commit it.
If you plan to use the TCMB macroeconomic data agent to query Turkish Central Bank EVDS indicators, initialize the local Qdrant collections (datagroups and series):
.\.venv\Scripts\Activate.ps1
# Requires TCMB_API_KEY and COHERE_API_KEY in .env
python backend/utils/tcmb_rag.py- Extraction & Caching: Queries the EVDS API for all datagroups and series, caching the structured result into
backend/database/clean_datagroups_with_series.json. If the file already exists, it skips EVDS calls and proceeds directly to vector indexing. - Indexing: Embeds datagroups and series using Cohere
embed-v4.0and upserts them into the local Qdrant vector store (backend/database/vectorstore). - CLI Options:
--skip-embed: Only extract and updatebackend/database/clean_datagroups_with_series.jsonwithout embedding to Qdrant.--force-extract: Force re-downloading from the EVDS API even if the JSON exists.--batch-size 32: Adjust Cohere embedding batch size.
Start the backend, then start the desktop client in a second terminal:
.\.venv\Scripts\Activate.ps1
python backend_runner.py.\.venv\Scripts\Activate.ps1
python frontend_runner.pySuccess state: GET http://127.0.0.1:8001/health returns JSON and the Electron window opens. The first start takes longer while local stores initialize.
To package a Windows x64 NSIS installer after npm ci:
Set-Location frontend
$env:CSC_IDENTITY_AUTO_DISCOVERY = "false"
npm run build
Set-Location ..The installer is written to frontend/dist/. The packaged desktop client still expects a separately running local backend.
- Upload a central bank inflation report (PDF). Azure Document Intelligence extracts page-aware Markdown, tables, and figures; chunks are embedded with Cohere and indexed in Qdrant and BM25.
- Ask: "How did the inflation forecast change, and which factors were positive?" The coordinator runs hybrid retrieval over the selected report and returns an answer with source cards plus the relevant table and chart images. It can call the TCMB agent to ground the answer in official series.
- Ask: "Compare these two stocks over the last quarter and give me a report." The coordinator calls the finance agent for end-of-day prices, the plotting agent for an interactive chart, and the file agent, which generates a Word document in an E2B sandbox. The chart and the document are returned as attachments.
- Select several contracts and enable SPD-RAG. Ask: "Across all of these contracts, which ones...". One worker researches each document in parallel; the findings are clustered and synthesized into one answer returned with document source cards while the client shows per-document progress.
The Electron client talks to a local FastAPI process on 127.0.0.1:8001 over HTTP and Server-Sent Events. A LangGraph coordinator owns the conversation and calls specialists as tools; specialists do not call each other. Persistent document copies and indexes are stored on the machine. Parsing, embedding, model inference, and generated-code execution use external providers, and all model-generated code runs in remote E2B sandboxes rather than on the host.
Select any diagram to open its full-size SVG.
The report-generation path below shows the coordinator sequencing finance, plotting, and file-generation specialists. Nested tool progress and final artifacts return to the client through the same SSE stream.
Uploaded files pass through format-aware parsing, contextual chunk headers, and hybrid indexing. Text and structured content are searchable through Qdrant and BM25, while extracted figures follow a multimodal embedding path.
Read the technical architecture deep dive for component responsibilities, request flow, agent guardrails, retrieval internals, reliability mechanisms, and design rationale.
Standard RAG shares one top-k budget across the whole corpus, so evidence from lower-ranked documents is dropped on questions like "compare X across all reports". SPD-RAG (Sub-Agent Per Document RAG) decomposes retrieval along the document axis: a reasoning model writes a shared task list, one bounded worker researches each document in parallel, and findings are clustered and summarized in token-budgeted batches until one answer remains.
- Paper: arXiv:2603.08329
- Implementation in this repository:
backend/core/spdrag/ - Benchmark code and data: NebulAICompany/SPD-RAG
- Citation:
CITATION.cff
Results reported in the paper on the Loong benchmark (English, 200k-250k token instances, 102 cases, GPT-5 as judge; higher score is better):
| System | Average score | Cost per query (USD) |
|---|---|---|
| Full-context baseline | 68.0 | 0.273 |
| Normal RAG | 33.0 | 0.080 |
| Agentic RAG | 32.8 | 0.098 |
| SPD-RAG | 58.1 | 0.103 |
In that evaluation SPD-RAG reached 85.4% of full-context quality at 37.9% of its API cost. The paper used Gemini 2.5 Pro and Flash; this repository uses GPT-5 and GPT-5-mini in the same roles. The table reproduces the paper's numbers and is not a benchmark run from this repository.
Agent behavior is evaluated with trajectory scoring: tests/test_trajectory/test.py runs the coordinator on sampled queries, scores each full trajectory with an LLM judge (agentevals), and applies heuristics for redundant or looping tool calls. It calls live providers and writes a metrics.txt report.
.\.venv\Scripts\Activate.ps1
python tests/test_trajectory/test.pyBenchmark results for SPD-RAG come from the paper and its evaluation repository.
AIris uses bring-your-own credentials. Each provider may charge for requests.
| Provider | Feature | Data sent | Key |
|---|---|---|---|
| Anthropic | Coordinator and specialist agents | Prompts and retrieved context | ANTHROPIC_API_KEY (startup) |
| OpenAI | Moderation, SPD-RAG, summarization, news, vision | Prompts, retrieved context, figure images | OPENAI_API_KEY (startup) |
| Cohere | Embeddings and reranking | Document chunks, figures, and queries | COHERE_API_KEY (startup) |
| Tavily | Web search | Search queries | TAVILY_API_KEY (startup) |
| Qwen | Alternative coordinator and specialist model | Prompts and retrieved context | QWEN_API_KEY (optional unless selected in code) |
| Azure Document Intelligence | PDF and Word parsing | Uploaded document content | AZURE_DOCUMENT_INTELLIGENCE_ENDPOINT (startup), AZURE_DOCUMENT_INTELLIGENCE_KEY |
| E2B | Sandboxed chart and Office generation | Generated code and referenced files | E2B_API_KEY |
| Marketstack | Market data and dashboard | Symbol and date requests | MARKETSTACK_API_KEY |
| TCMB EVDS | Turkish Central Bank series | Series codes and date ranges | TCMB_API_KEY |
| Wolfram Alpha | Computation | Query text | WOLFRAM_APP_ID |
| GoldAPI or MetalpriceAPI | Live gold prices in the desktop widget | Price requests | GOLDAPI_KEY or METALPRICEAPI_KEY |
| cdnjs, jsDelivr, Google Fonts | Renderer styles, fonts, and client-side libraries | Standard network request metadata | None |
Optional: QWEN_API_KEY, DEEPSEEK_API_KEY, and LangSmith tracing variables. Full variable list: .env.example.
- The Electron client and FastAPI backend run on the local machine. Persistent chat history, uploads, and indexes are stored under
backend/database/, which is ignored by git; the embedded Qdrant and BM25 data live underbackend/database/vectorstore/. - Document content leaves the machine when it is parsed (Azure), embedded or reranked (Cohere), included in a prompt (model providers), or staged for generation (E2B), as listed above.
- Main-chat web search is off unless the user enables it for a query; news-story chat includes web search.
- The renderer loads selected styles, fonts, and libraries from public CDNs when the application starts.
- The API binds to loopback. CORS is limited to the desktop origins and is not a boundary for other local processes. Run it on a trusted machine and do not expose port
8001.
| Kind | Extensions |
|---|---|
| Documents | .pdf, .docx, .txt |
| Spreadsheets | .xlsx, .xls |
| Images | .png, .jpg, .jpeg, .gif, .bmp |
- Single-user desktop application; no multi-tenant or hosted deployment.
- Model outputs are non-deterministic and depend on the configured providers; provider outages affect the corresponding features.
- The default coordinator model is Claude Sonnet 4.6. OpenAI, Qwen, and DeepSeek clients are available as alternatives; switching is a code change.
- Benchmark results above come from the paper, not from a committed evaluation run in this repository.
- Local frontend tests exist (
frontendnpm test). Broader automated unit coverage is not yet part of the project; evaluation still relies on trajectory scoring and manual verification of workflows.
| Document | Content |
|---|---|
| ARCHITECTURE.md | Components, request flow, ingestion, SPD-RAG internals, design decisions |
| CONTRIBUTING.md | Environment setup, pull-request expectations, verifying changes |
| CODE_OF_CONDUCT.md | Contributor Covenant 2.1, with project enforcement contact |
| SECURITY.md | Vulnerability reporting and scope |
| CITATION.cff | Machine-readable citation metadata |
| LICENSE | PolyForm Noncommercial License 1.0.0 |
| NOTICE | Required copyright notice |
.env.example |
Environment variable reference |
| Area | Start here |
|---|---|
| Desktop client | frontend/src/main.js, frontend/src/renderer/scripts/app.js |
| FastAPI routes and SSE | backend/app/main.py, backend/app/router.py |
| Coordinator and stream processing | backend/core/agents.py, backend/core/runner.py, backend/pipeline/query.py |
| Specialist agents and tools | backend/core/tools/agent_as_tools.py, backend/core/tools/ |
| Ingestion and retrieval | backend/pipeline/upload.py, backend/retrieval/ |
| SPD-RAG | backend/core/spdrag/graph.py, backend/core/spdrag/nodes.py |
| Sandboxed generation and state | backend/core/tools/file_tools.py, backend/core/checkpointer.py |
| Trajectory evaluation | tests/test_trajectory/test.py, tests/test_trajectory/judge.py |
AIris was developed by a five-person founding team spanning AI engineering, full-stack development, finance, and business development. Competing as team NebulAI, it placed third in the TEKNOFEST 2025 Financial Technologies competition.
Contributions are welcome. See CONTRIBUTING.md for setup, pull-request expectations, and how to verify changes that depend on external providers. Contributions are accepted under the project license.
The backend binds to loopback. CORS is limited to the desktop origins. The Electron main process opens only credential-free HTTP(S) links and keeps gold API keys out of the renderer. Do not open public issues for vulnerabilities. Follow the process in SECURITY.md.
If you use SPD-RAG or this implementation in academic work, cite the paper:
@misc{akay2026spdrag,
title = {SPD-RAG: Sub-Agent Per Document Retrieval-Augmented Generation},
author = {Yagiz Can Akay and Muhammed Yusuf Kartal and Esra Alparslan and Faruk Ortakoyluoglu and Arda Akpinar},
year = {2026},
eprint = {2603.08329},
archivePrefix = {arXiv},
primaryClass = {cs.CL},
doi = {10.48550/arXiv.2603.08329},
url = {https://arxiv.org/abs/2603.08329}
}GitHub also exposes CITATION.cff via Cite this repository.
AIris is licensed under the PolyForm Noncommercial License 1.0.0. You may use, modify, and share the software for noncommercial purposes, including personal study, research, and use by educational and other noncommercial organizations, under the terms in LICENSE. Commercial use requires a separate agreement — contact nebulaicompany@gmail.com.
Required Notice: Copyright 2025-2026 Nebula Intelligence team
This is a source-available license, not an OSI-approved open-source license, so GitHub may not detect it automatically. The license does not require attribution in publications, but if you build on SPD-RAG or this implementation in academic work, we ask that you cite the paper as shown in Citation.