Skip to main content
We welcome contributions to Finance Agent! This guide will help you get started with contributing code, reporting issues, and submitting pull requests.

​
Getting Started

Before contributing, please:
  1. Read through the main README to understand the project
  2. Review the Agent System Documentation for architecture details
  3. Check existing issues and pull requests

​
Development Setup

1

Clone the repository

git clone https://github.com/kamathhrishi/stratalensai.git
cd finance_agent
2

Install dependencies

pip install -r requirements.txt
3

Configure environment

Copy the example environment file and add your API keys:
cp .env.example .env
Required environment variables:
  • OPENAI_API_KEY - For embeddings and LLM features
  • API_NINJAS_KEY - For earnings transcripts
  • CEREBRAS_API_KEY - For fast inference (optional)
  • DATABASE_URL - PostgreSQL connection string
  • CLERK_SECRET_KEY / CLERK_PUBLISHABLE_KEY - For authentication (production)
See .env.example for the complete list.
4

Set up the database

Ensure PostgreSQL is running with the pgvector extension:
# Install pgvector extension in your database
psql $DATABASE_URL -c "CREATE EXTENSION IF NOT EXISTS vector;"
5

Run the development server

python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
The application will be available at http://localhost:8000.

​
Code Style Guidelines

​
Python Code Standards

Finance Agent follows these Python conventions: 
# Files: snake_case.py
# Classes: PascalCase
class RAGAgent:
    pass

# Functions and variables: snake_case
def search_similar_chunks(query, top_k):
    chunk_count = 10
    return results

# Constants: UPPER_SNAKE_CASE
MAX_ITERATIONS = 4
DEFAULT_CONFIDENCE_THRESHOLD = 0.90

​
FastAPI Patterns

Follow these patterns for API endpoints: 
from fastapi import APIRouter, Depends, HTTPException
from app.schemas import ResponseModel, RequestModel
from app.dependencies import get_current_user, get_db

router = APIRouter()

@router.post("/endpoint", response_model=ResponseModel)
async def endpoint_function(
    request_data: RequestModel,
    current_user: dict = Depends(get_current_user),
    db: asyncpg.Connection = Depends(get_db)
):
    """Clear docstring explaining endpoint purpose."""
    try:
        # Implementation
        return ResponseModel(success=True, data=result)
    except Exception as e:
        logger.error(f"Error in endpoint: {e}")
        raise HTTPException(status_code=500, detail=str(e))

​
Security Best Practices

Never commit sensitive information:
  • API keys and tokens
  • Database credentials
  • .env files
  • User data or PII
  • Always use parameterized queries (never string concatenation)
  • Validate and sanitize all user inputs
  • Use appropriate HTTP status codes (400, 401, 403, 404, 500)
  • Log errors with context but never log sensitive data

​
Project Structure

Understanding the codebase organization: 
finance_agent/
├── agent/                  # AI agent & RAG system
│   ├── llm/               # LLM clients (OpenAI/Cerebras)
│   ├── rag/               # RAG implementation
│   │   ├── rag_agent.py   # Main orchestration
│   │   ├── search_engine.py # Hybrid search
│   │   ├── sec_filings_service_smart_parallel.py # SEC agent
│   │   └── data_ingestion/ # Data pipelines
│   ├── prompts.py         # LLM prompt templates
│   └── agent_config.py    # Agent configuration
├── app/                   # FastAPI application
│   ├── routers/           # API route handlers
│   └── schemas/           # Pydantic models
├── frontend/              # React + TypeScript UI
├── db/                    # Database utilities
└── analytics/             # Usage tracking

​
Making Changes

1

Create a feature branch

git checkout -b feature/your-feature-name
Use descriptive branch names:
  • feature/add-10q-support for new features
  • fix/search-timeout for bug fixes
  • refactor/improve-caching for refactoring
2

Make your changes

  • Follow the code style guidelines above
  • Add docstrings to new functions and classes
  • Update relevant documentation
  • Keep commits focused and atomic
3

Test your changes

Run the application locally and verify your changes work:
# Start the server
python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

# Test the API endpoints
curl http://localhost:8000/docs
See Testing Guide for more details.
4

Commit your changes

Use clear, descriptive commit messages:
git add .
git commit -m "feat: add support for 10-Q quarterly filings"
Commit message format:
type(scope): brief description

- Detailed change 1
- Detailed change 2
Types: feat, fix, refactor, docs, test, chore

​
Pull Request Process

1

Push your branch

git push origin feature/your-feature-name
2

Open a pull request

Go to the repository and click New Pull Request.Your PR description should include:
  • What: Summary of changes
  • Why: Motivation and context
  • How: Implementation approach
  • Testing: How you tested the changes
  • Screenshots: If UI changes are involved
3

Address review feedback

Maintainers will review your PR and may request changes. Please:
  • Respond to feedback promptly
  • Make requested changes in new commits
  • Re-request review when ready
4

Merge

Once approved, a maintainer will merge your PR. Thank you for contributing!

​
Contribution Guidelines

​
Documentation

Do create documentation when:
  • Adding new major features requiring setup
  • Creating public APIs for external developers
  • User explicitly requests documentation
Do NOT create documentation automatically for:
  • Routine code changes
  • Internal refactoring
  • Minor bug fixes
Prefer inline code comments for complex logic.

​
File Management

  • Always prefer editing existing files over creating new ones
  • Never create helper scripts or temporary files unless necessary
  • Clean up temporary files immediately after use
  • Ask for clarification if requirements are ambiguous

​
Code Quality

  • Write clear, self-documenting code
  • Add comments for complex logic
  • Use existing helper functions and utilities
  • Handle errors gracefully with appropriate logging
  • Maintain backward compatibility when possible

​
Reporting Issues

Found a bug or have a feature request? Please open an issue. For bugs, include:
  • Clear description of the issue
  • Steps to reproduce
  • Expected vs actual behavior
  • Environment details (OS, Python version, etc.)
  • Relevant logs or error messages
For feature requests, include:
  • Use case and motivation
  • Proposed solution or approach
  • Any alternatives considered

​
Community

Questions or need help?

​
License

By contributing, you agree that your contributions will be licensed under the MIT License.

Build docs developers (and LLMs) love

Get started for freeTalk to us