Skip to content
simon-initPublic

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

9 Commits

Folders and files

Repository files navigation

PDForce

Extract financial data from Swedish annual reports (årsredovisningar) and link it to funding rounds — built for startup survival analysis research.

PDForce combines rule-based PDF table extraction with AI verification (Claude) to reliably pull 30+ standardized financial fields from messy, inconsistently formatted PDFs. It ships with a step-by-step React UI, a validation framework, and a self-improving knowledge base.


How It Works

PDForce runs three services locally:

Browser (React) ──► FastAPI backend ──► pdfplumber (rule-based extraction)
                                    └──► Claude AI (verification + correction)
                                    └──► SQLite database

Claude authentication is handled by a local Go proxy that reuses your existing Claude Code OAuth session — no Anthropic API key needed.

Extraction pipeline (per PDF)

  1. Rule-based extraction — pdfplumber reads tables from the PDF, detects the unit scale (tkr vs mkr), parses Swedish number formatting, and maps Swedish row labels to standardized field names (e.g. "Nettoomsättning" → revenue).
  2. AI verification — Claude reviews the raw extraction, fixes sign errors, fills in missed fields, flags suspicious values (e.g. negative equity), and logs lessons learned.
  3. Merge — AI-corrected fields override rule-based ones where confidence is higher.
  4. Validation — Nine checks run (balance sheet identity, sign conventions, required fields, cross-field relationships, etc.) and produce a quality score 0–100.
  5. Knowledge base update — Lessons from this run are stored and injected into future prompts, making each subsequent extraction more accurate.

Tech Stack

Layer Technology
Frontend React 18 + TypeScript, Vite, Tailwind CSS, shadcn/ui, Zustand, React Query
Backend Python 3.11+, FastAPI, Uvicorn (async), Pydantic v2
Database SQLite
PDF parsing pdfplumber, Pillow
AI Anthropic Claude via local OAuth proxy
AI proxy Go binary (ai-cli-proxy-api) — proxies Claude CLI OAuth to an OpenAI-compatible API on port 3456
Export openpyxl (XLSX), lxml (XML), CSV

Prerequisites

Tool Purpose Install
Claude Code CLI Provides the OAuth session the proxy uses npm install -g @anthropic-ai/claude-code
Go 1.21+ Builds the AI proxy binary go.dev/dl
Python 3.11+ Runs the FastAPI backend python.org
Node.js 18+ Runs the React frontend nodejs.org

Verify everything is installed:

claude --version
go version
python3 --version
node --version

Setup

1. Clone and enter the project

git clone <repo-url> pdfakta
cd pdfakta

2. Set up the backend

cd backend
python3 -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env               # Defaults work as-is for local dev
cd ..

3. Set up the frontend

cd frontend
npm install
cp .env.example .env
cd ..

4. Authenticate with Claude

The AI proxy reuses your existing Claude Code login. If you haven't authenticated yet:

claude login

This stores an OAuth token that the proxy will pick up automatically.

5. Start everything

./start.sh

This script:

  • Builds the Go proxy binary on first run (takes ~10 seconds)
  • Starts the AI proxy on port 3456
  • Starts the FastAPI backend on port 8000
  • Starts the Vite frontend on port 5173

Press Ctrl+C to stop all three.

Service URL
App http://localhost:5173
Backend API docs http://localhost:8000/docs
AI proxy health http://localhost:3456/health

Configuration

Backend (backend/.env)

The defaults work for local development out of the box.

# Where PDFs and exports are stored (created automatically on first run)
DATA_DIR=./data

# AI settings — also editable in the app under Settings
AI_MODEL=claude-sonnet-4-5-20250929
MAX_RETRIES=3
CONFIDENCE_THRESHOLD=70    # Fields below this score are flagged for review
AUTO_LEARN=true
AI_DELAY_SECONDS=1.0       # Pause between AI calls (avoids rate limiting)

AI Proxy (ai-cli-proxy-api/config.yaml)

Pre-configured for this project on port 3456. You don't need to touch this.


The Six-Step Workflow

PDForce follows a guided six-step workflow accessible from the sidebar.

Step 1 — Project setup Create a project (name and description). All data is scoped to this project.

Step 2 — Companies Add the companies whose annual reports you want to process. Supports one-by-one entry or bulk CSV import (company_name, org_number, sector).

Step 3 — Import PDFs Upload annual report PDFs. Each PDF is associated with a company and a fiscal year.

Step 4 — Extract data Run the extraction pipeline. You can process all unprocessed PDFs at once or select specific ones, pause and resume mid-run, and watch a real-time log. Expect 15–60 seconds per PDF depending on complexity.

Step 5 — Review Inspect extracted fields. Low-confidence fields are highlighted. You can edit values directly, see the per-PDF validation report, and view the quality heatmap across all companies and years.

Step 6 — Export Export the data as XLSX, CSV, or XML. A combined export merges financial data with funding rounds — this is the thesis format used for survival analysis.


Extracted Financial Fields

Income statement: revenue, gross_profit, operating_profit (EBIT), profit_before_tax, net_income, depreciation_amortization, interest_expense, interest_income, research_development_costs, personnel_costs, other_operating_expenses

Balance sheet — assets: total_assets, current_assets, non_current_assets, cash_and_equivalents, accounts_receivable, inventory

Balance sheet — liabilities & equity: total_liabilities, current_liabilities, non_current_liabilities, total_equity, accounts_payable, short_term_debt, long_term_debt

Cash flow: operating_cash_flow, investing_cash_flow, financing_cash_flow, capital_expenditures


The Knowledge Base

After each PDF is processed, PDForce records what it learned: Swedish label → field name mappings, formatting quirks, known error patterns for specific annual report templates. These are injected into the Claude prompt on future runs, making extraction progressively more accurate. You can view and edit the knowledge base from the sidebar.


Validation Checks

Each extraction is scored against nine rules:

  1. Balance sheet identity: total assets = total liabilities + equity
  2. Income statement consistency
  3. Sign conventions (revenues positive, costs negative)
  4. Required field presence
  5. Data type validity
  6. Cross-field plausibility (e.g. gross profit ≤ revenue)
  7. Extreme outlier detection
  8. Cash flow sign sanity
  9. Equity reasonableness (flags negative equity for review)

Manual Startup (without start.sh)

If you prefer separate terminals:

Terminal 1 — AI proxy

cd ai-cli-proxy-api
go build -o ai-cli-proxy-api ./cmd/...   # first time only
./ai-cli-proxy-api --config config.yaml

Terminal 2 — Backend

cd backend
source .venv/bin/activate
uvicorn app.main:app --reload --port 8000

Terminal 3 — Frontend

cd frontend
npm run dev

Troubleshooting

Proxy fails to start / "unauthorized" Run claude login and try again. The proxy needs a valid Claude Code OAuth session.

AI extraction returns empty results Check the proxy is running: curl http://localhost:3456/health. Confirm the backend .env has AI_MODE=cli.

PDF extraction finds no tables Some PDFs are scanned images with no machine-readable text. PDForce requires digitally-generated PDFs (not scanned). Vision/OCR extraction is planned but not yet available.

Balance sheet validation fails Common in real annual reports due to rounding. You can override individual field values in the Review step and re-validate.

Port already in use start.sh doesn't check for existing processes. Kill whatever is occupying the ports first:

lsof -ti:3456 | xargs kill -9
lsof -ti:8000 | xargs kill -9
lsof -ti:5173 | xargs kill -9

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages