IP Tax Reporter (iptax)

Automated IP tax report generator for Polish software developers participating in the 50% tax deduction program for creative work.

Features

• 🔍 Automatic change collection - Fetches merged PRs/MRs from GitHub/GitLab via psss/did
• 🤖 AI-assisted filtering - Uses Gemini or Vertex AI to identify product-related changes
• 📊 Workday integration - Retrieves work hours via SSO+Kerberos or manual input
• 📄 Bilingual PDF reports - Generates Polish/English tax reports and work cards
• 📚 History tracking - Prevents duplicate reporting with automatic date range management

Installation

Prerequisites

• Python 3.11 or higher
• did configured with your GitHub/GitLab credentials

System Dependencies

The tool requires system libraries for PDF generation (WeasyPrint), browser automation (Playwright Firefox), and Kerberos authentication (for git source install).

Fedora/RHEL/CentOS (dnf):

# Runtime libraries
sudo dnf install -y pango gdk-pixbuf2 gtk3 dbus-glib libXt alsa-lib krb5-libs

# Build dependencies (only needed for git source install)
sudo dnf install -y krb5-devel gcc python3-devel

Ubuntu/Debian (apt):

# Runtime libraries
sudo apt install -y libpango-1.0-0 libpangocairo-1.0-0 libgdk-pixbuf2.0-0 \
    libgtk-3-0 libdbus-glib-1-2 libxt6 libasound2 libkrb5-3

# Build dependencies (only needed for git source install)
sudo apt install -y libkrb5-dev gcc python3-dev

macOS (Homebrew):

brew install pango gdk-pixbuf gtk+3 dbus krb5

Using pipx (Recommended)

pipx install iptax

Using uvx (No Install)

Run directly without installation:

uvx iptax config
uvx iptax

From Source (Development)

git clone https://github.com/cardil/iptax.git
cd iptax
make init  # Creates venv and installs dependencies

Quick Start

1. Configure did

If you haven't already, configure did with your GitHub/GitLab credentials:

# Create ~/.did/config with your settings
did --config ~/.did/config

Example ~/.did/config:

[general]
email = your.email@example.com

[github]
type = github
url = https://api.github.com
token = ghp_your_token_here
login = your-github-username

2. Configure iptax

Run the interactive configuration wizard:

iptax config

This will prompt you for:

• Your full name (for reports)
• Product name (the project you're reporting on)
• AI provider settings (Gemini API key or Vertex AI project)
• Workday URL (optional)
• Creative work percentage (default: 100%)

3. Generate Your First Report

# Generate report for current month
iptax

# Or specify a month
iptax --month 2024-11

Usage

Main Commands

# Full report flow (collect → AI filter → review → generate)
iptax [--month YYYY-MM]

# Collect data only (PRs and work hours)
iptax collect [--month YYYY-MM]

# Review AI judgments interactively
iptax review [--month YYYY-MM]

# Generate output files from collected data
iptax dist [--month YYYY-MM]

Configuration Commands

# Interactive configuration
iptax config

# Show current configuration
iptax config --show

# Validate configuration
iptax config --validate

# Show config file path
iptax config --path

Cache Management

# List in-flight reports
iptax cache list

# Show cache statistics
iptax cache stats

# Clear caches
iptax cache clear [--ai] [--inflight] [--month YYYY-MM]

# Show cache paths
iptax cache path

History

# Show report history
iptax history

# Show specific month
iptax history --month 2024-11

# Output as JSON/YAML
iptax history --format json

Options

Option	Description
--month	Target month (auto-detect, 'current', 'last', or YYYY-MM)
--skip-ai	Skip AI filtering
--skip-review	Skip interactive review
--skip-workday	Skip Workday integration
--force	Discard existing in-flight data
--output-dir	Override output directory
--format	Output format (all, md, pdf)

Output Files

The tool generates three files in ~/Documents/iptax/YYYY/:

1. Markdown Report (YYYY-MM IP TAX Report.md)

   • List of all included changes with links
   • Grouped by repository

2. Work Card PDF (YYYY-MM IP TAX Work Card.pdf)

   • Bilingual (Polish/English) document
   • Lists product changes for tax authorities

3. Tax Report PDF (YYYY-MM IP TAX Raport.pdf)

   • Official monthly report
   • Work hours calculation
   • Copyright transfer declaration

Configuration

Configuration is stored in ~/.config/iptax/settings.yaml:

# Employee information
employee:
  name: "Jan Kowalski"
  supervisor: "Maria Nowak"

# Product being reported
product:
  name: "OpenShift Serverless"

# AI provider (gemini or vertex_ai)
ai:
  provider: gemini
  model: gemini-2.0-flash
  api_key: "your-api-key"

# Workday integration (optional)
workday:
  enabled: true
  url: "https://wd3.myworkday.com/yourcompany"
  auth: sso+kerberos
  trusted_uris:
    - "https://sso.yourcompany.com"

# Output settings
output:
  directory: "~/Documents/iptax"
  creative_work_percentage: 100

How It Works

1. Date Range Calculation - Determines the reporting period based on history and Polish tax law timing (26th-25th cycles)

2. Change Collection - Uses did to fetch merged PRs/MRs from configured GitHub/GitLab sources

3. AI Filtering - Sends changes to AI for relevance judgment, with caching to reduce API calls

4. Interactive Review - TUI interface for reviewing and overriding AI decisions

5. Work Hours - Retrieves hours from Workday or accepts manual input

6. Report Generation - Compiles data into Markdown and bilingual PDF reports

7. History Update - Records the report to prevent duplicate changes in future reports

Development

Setup

# Clone repository
git clone https://github.com/cardil/iptax.git
cd iptax

# Initialize development environment
make init

# Run tests
make verify

Make Targets

Target	Description
make init	Initialize development environment
make verify	Run all checks and tests
make test	Run unit and e2e tests
make unit	Run unit tests only
make e2e	Run e2e tests only
make check	Run lints and type checks
make format	Format code
make clean	Clean build artifacts

Project Structure

iptax/
├── src/iptax/           # Source code
│   ├── ai/              # AI filtering and cache
│   ├── cache/           # History and in-flight caches
│   ├── cli/             # Command-line interface
│   ├── config/          # Configuration management
│   ├── report/          # PDF/Markdown generation
│   ├── utils/           # Utilities
│   └── workday/         # Workday integration
├── tests/               # Test suite
│   ├── unit/            # Unit tests
│   └── e2e/             # End-to-end tests
├── docs/                # Documentation
└── Makefile             # Build automation

Troubleshooting

Configuration Issues

# Validate configuration
iptax config --validate

# Check config file location
iptax config --path

AI Cache Issues

# Clear AI cache if judgments seem wrong
iptax cache clear --ai

Workday Authentication

For SSO+Kerberos issues:

1. Ensure you have a valid Kerberos ticket: klist
2. Try with visible browser: iptax workday --foreground
3. Use password fallback: iptax workday --no-kerberos

Debug Snapshots: When authentication fails, debug snapshots (HTML pages and screenshots) are saved to ~/.cache/iptax/ for troubleshooting. These files may contain sensitive information - review and clean them up after resolving issues.

did Integration

# Test did configuration
did --since 2024-11-01 --until 2024-11-30

# Check did config location
cat ~/.did/config

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Make changes and test: make verify
4. Commit with conventional commits: git commit -m "feat: add feature"
5. Push and create PR: gh pr create

License

Apache 2.0 License - See LICENSE for details.

Acknowledgments

• psss/did - Change tracking tool
• WeasyPrint - PDF generation
• Playwright - Browser automation
• LiteLLM - AI provider abstraction
• Rich - Terminal UI
• Textual - TUI framework