TaxLens

NOTE: This is still under development!!!

TaxLens is a local web app that helps review the Internal Revenue Code for tax planning ideas.

It does three main things:

1. Reads a local Title 26 XML file.
2. Saves the tax code sections into a local SQLite database.
3. Sends sections to OpenAI or Claude and saves the planning strategies it finds.

The app runs on your computer. The database is local. API calls only happen when you click Run Analysis.

What You Need

Install these first:

• Python 3.11 or newer
• A local copy of the Title 26 XML file, or network access to download it from the U.S. Code site
• Either an OpenAI API key or a Claude API key

By default, TaxLens expects the XML file in this repo folder:

C:\Users\mick0\OneDrive\Documents\Code & Dev\GitHub\Tax-Lens\usc26.xml

If your XML file is somewhere else, you can change that later in .env.

Project Files

Important files:

• main.py: starts the web app and API.
• parser.py: reads the Title 26 XML file.
• tax_code_updater.py: checks the House U.S. Code release date and downloads Title 26 XML when needed.
• db.py: creates and reads the SQLite database.
• analyzer.py: sends tax code sections to OpenAI or Claude.
• frontend/index.html: browser interface.
• .env.template: example settings file.
• requirements.txt: Python packages needed by the app.
• CHANGELOG.md: dated record of repo changes.
• completed-upgrades.md: implemented upgrades moved out of future planning.
• assessment.md: detailed repo assessment that must stay current when the repo changes.
• AGENTS.md: repo instructions for future Codex work.

Generated local files:

• .env: your local settings and API key. Do not commit this.
• taxlens.db: local SQLite database. Do not commit this.
• taxlens.log: local app log. Do not commit this.
• usc26.xml: downloaded Title 26 XML file. Do not commit this.
• TaxCodeReleaseDate.txt: last downloaded House release date. Do not commit this.
• future-upgrades.md: local planning list for possible upgrades. Do not commit this.

Step 1: Open PowerShell In This Folder

From the repo folder:

cd "C:\Users\mick0\OneDrive\Documents\Code & Dev\GitHub\Tax-Lens"

Step 2: Create A Python Virtual Environment

Run:

python -m venv .venv

Activate it:

.\.venv\Scripts\Activate.ps1

If activation is blocked, run this once:

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

Then activate again:

.\.venv\Scripts\Activate.ps1

Step 3: Install Python Packages

Run:

pip install -r requirements.txt

This installs FastAPI, Uvicorn, XML parsing support, OpenAI support, Claude support, and environment file support.

Step 4: Create Your Settings File

Copy the template:

Copy-Item .env.template .env

Open it:

notepad .env

Step 5: Choose OpenAI Or Claude

Use OpenAI:

LLM_PROVIDER=openai
OPENAI_API_KEY=your_openai_key_here
OPENAI_MODEL=gpt-4o

Use Claude:

LLM_PROVIDER=claude
ANTHROPIC_API_KEY=your_claude_key_here
CLAUDE_MODEL=claude-3-5-sonnet-20241022

Leave the unused API key blank or keep the placeholder.

Step 6: Download Or Check The XML File

The default setting is:

XML_PATH=usc26.xml

To download the current Title 26 XML file, run:

python .\tax_code_updater.py

The updater checks the House U.S. Code download page. It reads the current release date at the top of the page. It compares that value to TaxCodeReleaseDate.txt.

If the dates do not match, it downloads the Title 26 XML zip, extracts usc26.xml into this repo folder, writes the new date to TaxCodeReleaseDate.txt, and deletes the zip file.

If your XML file is somewhere else, update XML_PATH.

Example:

XML_PATH=C:\Users\mick0\Documents\Data\usc26.xml

The default database setting is:

DB_PATH=taxlens.db

That is fine for normal local use.

Step 7: Start The App

Run:

uvicorn main:app --reload

Open this in your browser:

http://localhost:8000

First Run Behavior

When the app starts, it creates the local SQLite database.

If taxlens.db is empty and the XML file exists, the app parses the XML file and saves the tax code sections.

This can take a little time on the first run. Later runs are faster because the sections are already cached.

You can also click Parse XML in the browser to parse the XML manually.

Running Analysis

Click Run Analysis in the browser.

The app will:

1. Pull unanalyzed tax code sections from SQLite.
2. Send a batch to the selected LLM provider.
3. Save any returned strategies into taxlens.db.
4. Update the browser counts as findings are added.

The default batch size is 50 sections.

Full Title 26 analysis can cost money through the selected LLM API. A rough GPT-4o estimate is $5-15, depending on token volume and current pricing.

Browser Features

The browser UI lets you:

• View total sections, analyzed sections, and findings.
• Filter findings by strategy type.
• Search findings by keyword.
• Open a detailed strategy panel.
• Open the related Cornell LII tax code page.
• Start XML parsing.
• Check for a new Title 26 XML release.
• Start LLM analysis.

API Endpoints

These are mainly useful for testing or automation:

• GET /api/stats
• GET /api/findings?type=&keyword=&section=
• GET /api/findings/{id}
• POST /api/analyze?batch=50
• POST /api/parse
• POST /api/tax-code/update
• GET /api/sections

Example:

Invoke-RestMethod http://localhost:8000/api/stats

Repo Maintenance Files

Use these files to keep the project easy to resume:

• CHANGELOG.md: update this whenever repo behavior, docs, config, or workflow changes.
• assessment.md: update this every time a repo change is made. It is the detailed current state of the repo.
• future-upgrades.md: local only list of possible upgrades. It is ignored by Git.
• completed-upgrades.md: tracked list of upgrades after they are implemented and verified.

When an upgrade is completed, move it from future-upgrades.md to completed-upgrades.md, then log the change in CHANGELOG.md.

Troubleshooting

If uvicorn is not recognized, make sure the virtual environment is active and packages are installed:

.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt

If the app shows zero sections, check that the XML file exists:

Test-Path ".\usc26.xml"

If that returns False, run:

python .\tax_code_updater.py

Then click Parse XML in the browser, or restart the app.

If analysis returns no findings, check:

• LLM_PROVIDER is set to openai or claude.
• The matching API key is set.
• The API key has billing enabled.
• taxlens.log for errors.

If port 8000 is already in use, run on another port:

uvicorn main:app --reload --port 8001

Then open:

http://localhost:8001