{"id":41976369,"url":"https://github.com/nathan-au/teefour-ai","last_synced_at":"2026-07-03T20:31:54.135Z","repository":{"id":318809697,"uuid":"1074278267","full_name":"nathan-au/teefour-ai","owner":"nathan-au","description":"teefour-ai is a backend API for tax accounting automation","archived":false,"fork":false,"pushed_at":"2026-01-14T19:31:08.000Z","size":2033,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-26T13:25:26.594Z","etag":null,"topics":["fastapi","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nathan-au.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-11T13:40:29.000Z","updated_at":"2026-01-14T19:31:11.000Z","dependencies_parsed_at":"2025-10-16T05:21:47.089Z","dependency_job_id":"e04cda59-ec51-4930-b6f1-617d7de91589","html_url":"https://github.com/nathan-au/teefour-ai","commit_stats":null,"previous_names":["nathan-au/rpg-mini","nathan-au/teefour-ai"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/nathan-au/teefour-ai","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nathan-au%2Fteefour-ai","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nathan-au%2Fteefour-ai/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nathan-au%2Fteefour-ai/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nathan-au%2Fteefour-ai/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nathan-au","download_url":"https://codeload.github.com/nathan-au/teefour-ai/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nathan-au%2Fteefour-ai/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35101088,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-03T02:00:05.635Z","response_time":110,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fastapi","python"],"created_at":"2026-01-25T23:31:14.653Z","updated_at":"2026-07-03T20:31:54.129Z","avatar_url":"https://github.com/nathan-au.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# teefour-ai: AI-Powered Tax Accounting Automation\n\u003cimg width=\"2926\" height=\"1634\" alt=\"teefourai\" src=\"https://github.com/user-attachments/assets/90925cc5-024e-460f-ab16-f3ac00ad871b\" /\u003e\n\n## Project Overview\n\nTeeFour AI is an end-to-end backend framework designed to support accounting professionals who manage numerous clients and document intakes. The system automates repetitive administrative tasks, such as document collection, categorization, and field extraction, to allow accountants to focus on review and decision-making rather than manual data entry.\n\n## Key Features\n\n- **Client \u0026 Intake Management:** Manage clients by complexity and create separate intakes for each fiscal year to maintain organized tracking.  \n- **Smart Document Uploads:** Upload multiple files that are automatically validated, stored, and linked to the correct client intake.  \n- **Automated Document Classification:** Identify document types using OCR and keyword-based detection to eliminate manual sorting and accelerate intake verification.  \n- **Data Fields Extraction:** Extract information from scanned or photographed documents into structured data fields in the database.\n- **Dynamic Checklist Tracking:** Automatically update intake and checklist statuses as documents are classified and extracted.\n- **Batch and Single Processing:** Run classification or extraction on all intake documents at once or handle them individually for precise control.  \n\n## Architecture\n\nThe architecture follows a linear workflow: Client -\u003e Intake -\u003e Document Upload -\u003e Classification -\u003e Extraction -\u003e Checklist. Each stage is tied to domain models and API endpoints for automation and integration with downstream accounting processes.\n\n### 1. Client Creation\n**Endpoint:** `POST /clients/`  \nA client is created with basic information (name, email) and a complexity level (simple, average, complex). The complexity determines the number and types of expected documents for all future intakes and is permanent once set. For example, a \"simple\" client only requires a T4 and id, while a \"complex\" client also requires 5 receipts.\n\n### 2. Intake Creation\n**Endpoint:** `POST /intakes/`  \nAn intake represents a fiscal-year accounting case for a client. Upon intake creation, TeeFour AI generates a dynamic checklist based on the client's complexity and sets the intake status to open.\n\n### 3. Document Upload\n**Endpoint:** `POST /intakes/{intake_id}/documents`  \nDocuments can be uploaded in PDF, JPG, or PNG formats. Each file is validated, stored in an upload directory, and assigned a SHA256 hash to prevent duplicate uploads. Metadata such as file size, MIME type, and upload timestamp is also recorded.\n\n### 4. Document Classification\n**Endpoints:**  \nBatch: `POST /intakes/{intake_id}/classify`  \nSingle: `POST /documents/{document_id}/classify`\n\u003cbr\u003e\nTeeFour AI reads text using OCR (PyMuPDF + pytesseract) and applies rule-based logic for keyword matching. The algorithm first attempts to classify based on the filename. If this initial attempt is not successful, the document's content is then extracted using OCR and scanned for keywords. The document is ultimately classified as one of the known types (T4, receipt, or ID), or marked as unknown if neither layer provides a match. This two-step process ensures both efficiency for clearly named files and robustness for files that require content-based inspection.\n\n### 5. Data Extraction\n**Endpoints:**  \nBatch: `POST /intakes/{intake_id}/extract`  \nSingle: `POST /documents/{document_id}/extract`\n\u003cbr\u003e\nAfter classification, the program performs data extraction. OCR text is fed into a lightweight LLM (currently gemma3) with customized prompts to identify structured fields such as names, dates, income amounts, and employer details. The extracted values are saved to the database for reporting or export to accounting software. This step converts unstructured data (like a scanned T4) into structured, machine-readable form (JSON).\n\n### 6. Checklist Management and Intake Completion\n**Endpoint:** `GET /intakes/{intake_id}/checklist`  \nEach intake has a dynamic checklist that updates as documents are classified and extracted. When all required items are marked complete, the intake status automatically changes to \"done\". Throughout the process: \"open\" means intake created but no files yet, \"received\" means files uploaded and classified, and \"done\" meanas all expected documents extracted and checklist items completed.\n\n## Technologies Used\n- **Python** - Core programming language for all backend logic.\n- **FastAPI** - Python web framework used for all API endpoints.  \n- **SQLModel** - ORM for defining and managing relational data models.  \n- **SQLite** - Database for storing clients, intakes, documents, and extracted data.  \n- **pytesseract** - OCR engine for reading text from scanned images and PDFs.  \n- **ollama** - Local model runner used for structured field extraction from OCR text.  \n- **Uvicorn** - ASGI server for local or production deployment of the FastAPI app.\n\n## Installation\n\nFollow these steps to install and run TeeFour AI locally.\n\n### 1. Clone the Repository\n```bash\ngit clone https://github.com/nathan-au/teefour-ai.git\ncd teefour-ai\n```\n### 2. Create and Activate a Virtual Environment\n```bash\npython -m venv venv\nsource venv/bin/activate       # macOS / Linux\nvenv\\Scripts\\activate          # Windows\n```\n### 3. Install Required Packages\n```bash\npip install -r requirements.txt\n```\n### 4. Install Tesseract OCR \nmacOS:\n```bash\nbrew install tesseract\n```\nUbuntu/Debian:\n```bash\nsudo apt install tesseract-ocr\n```\nWindows: \n\u003cbr\u003e\nDownload and install from [https://github.com/tesseract-ocr/tesseract](https://github.com/tesseract-ocr/tesseract)\n\u003cbr\u003e\n\nVerify the installation:\n```bash\ntesseract --version\n```\n### 5. Install Ollama \nDownload and install from [https://ollama.com/download](https://ollama.com/download)\n\u003cbr\u003e\n\u003cbr\u003e\nVerify the installation:\n```bash\nollama --version\n```\nPull the Gemma3 model\n```bash\nollama pull gemma3\n```\nCheck that the model is available:\n```bash\nollama list\n```\nOllama usually runs automatically after installation. If it is not active, start it manually:\n```bash\nollama serve\n```\n### 6. Run the FastAPI Application\nStart the development server:\n```bash\nuvicorn main:app --reload\n```\nAccess the API:\n```bash\nhttp://localhost:8000\n```\nOpen the interactive API documentation\n```bash\nhttp://localhost:8000/docs\n```\n### 7. Try Example Workflow\n1.\tCreate a client -\u003e POST /clients/ \u003cbr\u003e\n2.\tCreate an intake -\u003e POST /intakes/ \u003cbr\u003e\n3.\tUpload documents -\u003e POST /intakes/{intake_id}/documents \u003cbr\u003e\n4.\tClassify documents -\u003e POST /intakes/{intake_id}/classify \u003cbr\u003e\n5.\tExtract data -\u003e POST /intakes/{intake_id}/extract \u003cbr\u003e\n6.\tCheck progress -\u003e GET /intakes/{intake_id}/checklist \u003cbr\u003e\n\n### 8. Run Tests (optional)\n```bash\npytest -v\n```\n\n## Future Improvements\n- **ML Document Classification/Extraction** - Integrate machine learning models for more precise classification and extraction (maybe using LayoutLM, transformers or Donut).  \n- **User Authentication/Authorization** - Add role-based access for clients/staff/admins with secure authentication and authorization.  \n- **Web-based Frontend** – Build a Vue.js interface for management of client/intake creation, document uploads, classification/extraction processes, and status checking with a nice UI.  \n- **Cloud Storage Integration** - Connect a cloud storage service for scalable backend document/data storage.  \n- **Isolated Testing Pipeline** - Create a dedicated test database and continuous integration pipeline for unit and integration testing.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnathan-au%2Fteefour-ai","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnathan-au%2Fteefour-ai","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnathan-au%2Fteefour-ai/lists"}