taxapex 1.0.1

Python SDK for the TaxApex Tax Notice Management API

TaxApex Python SDK

Official Python client library for the TaxApex Tax Notice Management API.

Installation

pip install taxapex

Quick Start

from taxapex import TaxApexClient

# Initialize the client
client = TaxApexClient(api_key="your-api-key")

# Extract data from a tax notice
result = client.extract.from_file("notice.pdf")
print(f"Notice Type: {result.notice_type}")
print(f"Amount Due: ${result.amount_due}")
print(f"Due Date: {result.due_date}")

Features

Document Extraction

Extract structured data from IRS and state tax notices:

# From a local file
result = client.extract.from_file("cp2000_notice.pdf")

# From raw bytes
with open("notice.pdf", "rb") as f:
    result = client.extract.from_bytes(f.read(), filename="notice.pdf")

# From a URL
result = client.extract.from_url("https://example.com/notice.pdf")

# Access extracted data
print(f"Notice Type: {result.notice_type}")
print(f"Issuing Agency: {result.issuing_agency}")
print(f"Amount Due: ${result.amount_due}")
print(f"Due Date: {result.due_date}")
print(f"Taxpayer: {result.taxpayer_name}")
print(f"Tax Year: {result.tax_year}")
print(f"Confidence: {result.confidence_score:.2%}")

Audit Risk Analysis

Analyze audit risk for clients:

# Analyze audit risk
risk = client.audit_risk.analyze(
    client_id="client-12345",
    tax_year=2023,
    income_data={
        "wages": 150000,
        "self_employment": 50000,
        "investments": 25000,
        "rental": 12000,
    },
    deduction_data={
        "mortgage_interest": 18000,
        "state_taxes": 10000,
        "charitable": 15000,
        "home_office": 5000,
    },
    industry="technology"
)

# Review results
print(f"Overall Risk Score: {risk.overall_score}/100")
print(f"Risk Level: {risk.risk_level}")
print(f"\nCategory Scores:")
print(f"  Income: {risk.income_score}/100")
print(f"  Deductions: {risk.deductions_score}/100")
print(f"  Credits: {risk.credits_score}/100")
print(f"  Compliance: {risk.compliance_score}/100")

print(f"\nRisk Factors:")
for factor in risk.risk_factors:
    print(f"  - {factor.description} ({factor.severity})")

print(f"\nRecommendations:")
for rec in risk.recommendations:
    print(f"  - {rec}")

Semantic Search

Search across your document repository:

# Search documents
results = client.search.query(
    "IRS penalty abatement procedures",
    document_type="IRS_NOTICE",
    limit=5,
    min_similarity=0.7
)

print(f"Found {results.total_results} results:")
for item in results.results:
    print(f"\n{item.title}")
    print(f"  Similarity: {item.similarity_score:.2%}")
    print(f"  Snippet: {item.content_snippet[:100]}...")

# Index a new document
client.search.index_document(
    document_id="doc-123",
    content="Full text content of the document...",
    title="CP2000 Response Letter",
    document_type="RESPONSE_LETTER",
    tax_year=2023
)

Tax Research

Get AI-powered answers to tax questions:

# Research a tax question
result = client.research.query(
    "What are the requirements for claiming the home office deduction?",
    include_citations=True,
    max_sources=5
)

print(f"Answer:\n{result.answer}")
print(f"\nConfidence: {result.confidence:.2%}")
print(f"\nSources:")
for source in result.sources:
    print(f"  - {source.title}")
    print(f"    {source.url}")

Usage Statistics

Monitor your API usage:

usage = client.get_usage()

print(f"Billing Period: {usage.period_start} to {usage.period_end}")
print(f"Document Extractions: {usage.document_extractions}")
print(f"AI Analysis Calls: {usage.ai_analysis_calls}")
print(f"Search Queries: {usage.search_queries}")
print(f"Audit Risk Assessments: {usage.audit_risk_assessments}")
print(f"Total API Calls: {usage.total_api_calls}")

Configuration

Environment Variables

export TAXAPEX_API_KEY="your-api-key"
export TAXAPEX_BASE_URL="https://api.taxapex.com/v1"  # Optional

Client Options

client = TaxApexClient(
    api_key="your-api-key",
    base_url="https://api.taxapex.com/v1",  # Custom API URL
    timeout=120,  # Request timeout in seconds
    max_retries=5,  # Retry attempts for failed requests
    retry_delay=2.0,  # Base delay between retries
)

Context Manager

with TaxApexClient(api_key="your-api-key") as client:
    result = client.extract.from_file("notice.pdf")
    # Session is automatically closed

Error Handling

from taxapex import (
    TaxApexClient,
    APIError,
    AuthenticationError,
    RateLimitError,
    ValidationError,
)

try:
    result = client.extract.from_file("notice.pdf")
except AuthenticationError:
    print("Invalid API key")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after} seconds")
except ValidationError as e:
    print(f"Invalid request: {e.message}")
except APIError as e:
    print(f"API error: {e.message} (status: {e.status_code})")

Data Models

ExtractionResult

Field	Type	Description
id	str	Unique extraction ID
notice_type	NoticeType	Type of notice (CP2000, CP501, etc.)
issuing_agency	str	IRS or state agency
notice_date	datetime	Date on the notice
due_date	datetime	Response due date
amount_due	float	Amount owed
taxpayer_name	str	Taxpayer name
taxpayer_id	str	SSN/EIN (masked)
tax_year	int	Tax year
fields	List[ExtractedField]	All extracted fields
confidence_score	float	Extraction confidence (0-1)

AuditRiskAssessment

Field	Type	Description
id	str	Assessment ID
client_id	str	Client identifier
tax_year	int	Tax year analyzed
overall_score	float	Overall risk score (0-100)
risk_level	RiskLevel	low, medium, high, critical
income_score	float	Income risk score
deductions_score	float	Deductions risk score
credits_score	float	Credits risk score
compliance_score	float	Compliance risk score
risk_factors	List[RiskFactor]	Identified risk factors
recommendations	List[str]	Mitigation recommendations

Support

• Documentation: https://docs.taxapex.com
• Email: [e-mail]
• GitHub Issues: https://github.com/innorve/taxapex-python/issues

License

MIT License - see LICENSE file for details.