{"id":38516638,"url":"https://github.com/janhelcl/valuagent","last_synced_at":"2026-01-17T06:31:25.586Z","repository":{"id":309552124,"uuid":"1023786001","full_name":"janhelcl/valuagent","owner":"janhelcl","description":null,"archived":false,"fork":false,"pushed_at":"2025-10-05T08:31:55.000Z","size":12736,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-05T10:26:31.159Z","etag":null,"topics":["accounting","ai","genai","valuation"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/janhelcl.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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-07-21T17:32:43.000Z","updated_at":"2025-10-05T08:31:59.000Z","dependencies_parsed_at":"2025-10-05T10:17:58.725Z","dependency_job_id":"6591d08a-434c-4cc0-ac1b-235c627df12e","html_url":"https://github.com/janhelcl/valuagent","commit_stats":null,"previous_names":["janhelcl/valuagent"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/janhelcl/valuagent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/janhelcl%2Fvaluagent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/janhelcl%2Fvaluagent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/janhelcl%2Fvaluagent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/janhelcl%2Fvaluagent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/janhelcl","download_url":"https://codeload.github.com/janhelcl/valuagent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/janhelcl%2Fvaluagent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28502360,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T04:31:57.058Z","status":"ssl_error","status_checked_at":"2026-01-17T04:31:45.816Z","response_time":85,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["accounting","ai","genai","valuation"],"created_at":"2026-01-17T06:31:25.505Z","updated_at":"2026-01-17T06:31:25.564Z","avatar_url":"https://github.com/janhelcl.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Valuagent\n\n**AI-powered OCR and validation system for Czech financial statements**\n\nValuagent is a sophisticated FastAPI application that extracts, validates, and processes Czech financial statements (Rozvaha - Balance Sheet, Výkaz zisku a ztráty - Profit \u0026 Loss Statement) from PDF annual reports using Google's Gemini AI models. The system provides automated OCR with intelligent validation rules and exports clean, structured data to Excel format.\n\n## 🚀 Key Features\n\n### 📄 Intelligent PDF Processing\n- **Multi-format OCR**: Extracts financial data from Czech annual report PDFs\n- **Automatic Statement Detection**: Identifies whether PDFs contain Balance Sheet, P\u0026L, or both\n- **Retry Logic**: Configurable OCR retry attempts for improved accuracy\n- **Multi-file Processing**: Handle multiple PDF files simultaneously\n\n### 🔍 Advanced Validation System\n- **Business Rule Validation**: Pre-configured validation rules for Czech accounting standards\n- **Tolerance Settings**: Configurable tolerance for rounding differences (common in \"tis. Kč\" statements)\n- **Hierarchical Validation**: Validates parent-child relationships between financial line items\n- **Error Reporting**: Detailed validation reports with specific error descriptions\n\n### 📊 Data Export \u0026 Analysis\n- **Excel Export**: Structured Excel workbooks with validation reports\n- **JSON Output**: Clean, validated JSON data following Czech accounting standards\n- **Validation Reports**: Dedicated sheets showing validation results and potential issues\n- **Data Mapping**: Intelligent mapping of Czech financial statement line items\n\n### 🌐 Modern Web Interface\n- **Drag \u0026 Drop Upload**: Intuitive file upload interface\n- **Real-time Processing**: Async processing with progress feedback\n- **Multi-language Support**: Czech language interface and error messages\n- **Responsive Design**: Works on desktop and mobile devices\n\n### 🛡️ Enterprise Features\n- **Rate Limiting**: Built-in API rate limiting for production use\n- **Authentication**: Optional authentication system\n- **Logging**: Comprehensive logging with Google Cloud Logging support\n- **Docker Support**: Production-ready Docker containerization\n\n## 🏗️ Architecture Overview\n\nValuagent follows a clean, domain-driven architecture:\n\n```\nsrc/\n├── app/                    # FastAPI application layer\n│   ├── api/               # API routes and endpoints\n│   └── main.py            # Application entry point\n├── domain/                # Core business logic\n│   ├── models/           # Pydantic models for financial statements\n│   └── prompts/          # AI prompts for OCR processing\n├── infrastructure/       # External services and utilities\n│   ├── clients/         # AI client integrations (Google Gemini)\n│   ├── exporters/       # Excel and data export functionality\n│   └── resources/       # Static resources and mappings\n├── services/            # Application services\n└── shared/              # Shared utilities\n```\n\n### Core Components\n\n- **Domain Models**: Pydantic-based models for Balance Sheet and P\u0026L statements with built-in validation\n- **Validation Rules**: Configurable business rules that validate financial statement consistency\n- **OCR Engine**: Google Gemini-powered OCR with specialized prompts for Czech financial documents\n- **Export System**: Excel generation with formatted output and validation reports\n\n## 🛠️ Setup \u0026 Installation\n\n### Prerequisites\n\n- **Python 3.10+**\n- **Poetry** (for dependency management)\n- **Google AI API Key** (for Gemini models)\n\n### Local Development\n\n1. **Clone the repository**:\n```bash\ngit clone \u003crepository-url\u003e\ncd valuagent\n```\n\n2. **Install dependencies**:\n```bash\npoetry install\n```\n\n3. **Set environment variables**:\n```bash\n# Windows\nset GOOGLE_API_KEY=your_gemini_api_key_here\nset GENAI_MODEL=gemini-2.5-pro\n\n# Linux/macOS\nexport GOOGLE_API_KEY=your_gemini_api_key_here\nexport GENAI_MODEL=gemini-2.5-pro\n```\n\n4. **Start the development server**:\n```bash\npoetry run uvicorn src.app.main:app --reload --host 0.0.0.0 --port 8000\n```\n\n5. **Access the application**:\n   - Web interface: http://localhost:8000\n   - API documentation: http://localhost:8000/docs\n\n### Docker Deployment\n\n1. **Build the Docker image**:\n```bash\ndocker build -t valuagent .\n```\n\n2. **Run the container**:\n```bash\ndocker run -p 8080:8080 \\\n  -e GOOGLE_API_KEY=your_api_key \\\n  -e GENAI_MODEL=gemini-2.5-pro \\\n  valuagent\n```\n\n### Environment Variables\n\n| Variable | Description | Default | Required |\n|----------|-------------|---------|----------|\n| `GOOGLE_API_KEY` | Google AI API key for Gemini models | - | Yes |\n| `GENAI_MODEL` | Gemini model to use | `gemini-2.5-pro` | No |\n| `LOG_LEVEL` | Logging level | `INFO` | No |\n| `SESSION_SECRET` | Secret key for sessions | `change-this-in-prod` | No |\n| `PORT` | Server port | `8080` | No |\n\n## 📖 API Documentation\n\n### Endpoints\n\n#### `GET /`\nReturns the main web interface for file upload.\n\n#### `POST /process`\nProcess uploaded PDF files and return Excel or JSON output.\n\n**Parameters:**\n- `pdfs` (file, multiple): PDF files to process\n- `tolerance` (int, default=1): Tolerance for validation rules\n- `return_json` (bool, default=false): Return JSON instead of Excel\n- `ocr_retries` (int, optional): Max OCR retry attempts\n\n**Response:**\n- Success: Excel file download or JSON data\n- Error: JSON error message with details\n\n### Example Usage\n\n#### Using the Web Interface\n1. Navigate to http://localhost:8000\n2. Drag and drop PDF files or click to select\n3. Adjust tolerance settings if needed\n4. Click \"Zpracovat a stáhnout Excel\" to process\n\n#### Using the API with curl\n```bash\ncurl -X POST \"http://localhost:8000/process\" \\\n  -F \"pdfs=@annual_report.pdf\" \\\n  -F \"tolerance=1\" \\\n  -F \"return_json=false\"\n```\n\n#### Using Python requests\n```python\nimport requests\n\nwith open('annual_report.pdf', 'rb') as f:\n    response = requests.post(\n        'http://localhost:8000/process',\n        files={'pdfs': f},\n        data={'tolerance': 1, 'return_json': False}\n    )\n\n# Save Excel file\nwith open('output.xlsx', 'wb') as f:\n    f.write(response.content)\n```\n\n## 🎯 Supported Financial Statements\n\n### Balance Sheet (Rozvaha)\n- **Assets**: Current and non-current assets\n- **Liabilities**: Current and long-term liabilities  \n- **Equity**: Share capital, retained earnings, reserves\n- **Validation Rules**: Asset-liability balance, hierarchical summations\n\n### Profit \u0026 Loss Statement (Výkaz zisku a ztráty)\n- **Revenue**: Operating revenue, financial income\n- **Expenses**: Operating expenses, financial costs, taxes\n- **Results**: Operating profit, profit before/after tax\n- **Validation Rules**: Revenue-expense calculations, profit derivations\n\n## 🔧 Configuration\n\n### Tolerance Settings\nThe tolerance parameter allows for small rounding differences common in Czech financial statements (typically reported in thousands of CZK):\n\n- `0`: Exact validation (no tolerance)\n- `1`: Allow ±1 unit difference (recommended)\n- `2+`: Higher tolerance for less precise documents\n\n### OCR Retry Configuration\nConfigure retry attempts for improved accuracy:\n- Default: 3 retries\n- Maximum: 5 retries\n- Minimum: 1 attempt\n\n## 🧪 Development\n\n### Project Structure\nThe project follows clean architecture principles with clear separation of concerns:\n\n- **Domain Layer**: Business logic and validation rules\n- **Application Layer**: API endpoints and request handling  \n- **Infrastructure Layer**: External services and data persistence\n- **Shared Layer**: Common utilities and helpers\n\n### Running Tests\n```bash\npoetry run pytest\n```\n\n### Code Quality\n```bash\n# Format code\npoetry run black src/\n\n# Type checking\npoetry run mypy src/\n\n# Linting\npoetry run flake8 src/\n```\n\n### Jupyter Notebooks\nExplore the OCR functionality using the included Jupyter notebook:\n```bash\npoetry run jupyter lab notebooks/ocr.ipynb\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjanhelcl%2Fvaluagent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjanhelcl%2Fvaluagent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjanhelcl%2Fvaluagent/lists"}