ConvFinQA Project

A conversational financial question-answering system that handles numerical reasoning over unstructured financial documents containing data tables.

Overview

This project implements a system to handle conversational queries about financial data, supporting:

• Multi-turn conversations with context memory
• Numerical reasoning across financial documents
• Table data extraction and processing
• Two types of conversations:
  • Type I: Simple conversations (decomposed multi-hop questions)
  • Type II: Hybrid conversations (combined reasoning chains)

This is a prototype and prints logs.

Prerequisites

• Python 3.12+
• UV environment manager

Installation

1. Clone the repository

git clone <git@github.com:spyrosze/financial-agent.git>

2. Install dependencies using UV

# Install UV if not already installed
brew install uv

# Set up environment and install dependencies
uv sync

Usage

Chat Interface

Run the chat interface using:

uv run main chat <record_id>

Example:

uv run main chat "Single_RSG/2017/page_98.pdf-1"

Note: The record_id serves as thread_id for conversation memory (in-memory only, not persistent across runs).

Dataset

The project uses the ConvFinQA dataset, which includes:

• 3,892 conversations with 14,115 questions
• Train/Dev/Test split: 3,037/421/434 conversations
• Cleaned and preprocessed financial data
• Structured tables with numerical data

Dataset location: data/convfinqa_dataset.json

For detailed dataset information, see dataset.md.

Testing

The project uses pytest for testing. Tests are organized into:

• Unit tests
• Integration tests
• Example tests

Run tests using:

# Run all tests
uv run pytest

# Run specific test category
uv run pytest tests/unit/
uv run pytest tests/integration/

# Run with coverage
uv run pytest --cov=src tests/

Key test files:

• Integration tests:
  • tests/integration/test_multiturn_chat_flow.py
  • tests/integration/test_single_turn_chat_flow.py
• Unit tests:
  • tests/unit/test_doc_retriever.py
  • tests/unit/test_prompt_designer.py
  • tests/unit/test_table_to_dataframe.py

Project Structure

├── analysis/              # Dataset Analysis notebooks and scripts
├── data/                  # Dataset files
├── src/
│   ├── agent/            # Core agent implementation
│   │   ├── models/       # Financial text analysis models
│   │   └── utils/        # Helper utilities
│   └── main.py           # CLI application
├── tests/                # Test suite
│   ├── fixtures/        # Test data including doc specific ids and types
│   ├── integration/     # Integration tests
│   └── unit/           # Unit tests

Development

• Code formatting: The project uses ruff for linting and formatting
• Type checking: mypy is configured for static type checking
• Dependencies are managed through pyproject.toml

License

Copyright (c) 2024 S Zevelakis - All Rights Reserved

This code is private and confidential, created as part of a coding assessment/test. Unauthorized copying, modification, distribution, or use of this code, via any medium, is strictly prohibited.

This code is provided for evaluation purposes only and may not be used for any other purpose without explicit written permission from the author.

NO WARRANTIES ARE PROVIDED, EXPRESS OR IMPLIED.

=

This README provides:

1. Clear installation and setup instructions
2. Usage examples for the chat interface
3. Information about the dataset
4. Testing instructions and structure
5. Project organization
6. Development tools and standards