{"id":51166826,"url":"https://github.com/titaniumcoder/invoicely","last_synced_at":"2026-06-26T20:02:10.680Z","repository":{"id":361711822,"uuid":"1255485966","full_name":"titaniumcoder/invoicely","owner":"titaniumcoder","description":"This is a simple chatbot example for myself to automatically create invoices that are auto-translated to bulgarian and signed for auditing. requirements for bulgarian tax logic and a good example on how to integrate an llm with external tools.","archived":false,"fork":false,"pushed_at":"2026-05-31T22:57:19.000Z","size":18,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-01T00:16:04.876Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/titaniumcoder.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":"2026-05-31T22:11:20.000Z","updated_at":"2026-05-31T22:57:22.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/titaniumcoder/invoicely","commit_stats":null,"previous_names":["titaniumcoder/invoicely"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/titaniumcoder/invoicely","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/titaniumcoder%2Finvoicely","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/titaniumcoder%2Finvoicely/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/titaniumcoder%2Finvoicely/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/titaniumcoder%2Finvoicely/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/titaniumcoder","download_url":"https://codeload.github.com/titaniumcoder/invoicely/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/titaniumcoder%2Finvoicely/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34831250,"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-06-26T02:00:06.560Z","response_time":106,"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":[],"created_at":"2026-06-26T20:02:09.778Z","updated_at":"2026-06-26T20:02:10.675Z","avatar_url":"https://github.com/titaniumcoder.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Invoicely\n\nA personal, terminal-based invoicing assistant. Invoicely turns\n[Toggl](https://toggl.com/) time entries into Bulgarian-compliant, dual-language\n(English + Bulgarian) invoices — drafted in a chat, confirmed by you, then\nrendered to a signed PDF and stored entirely in a [Proton Drive](https://proton.me/drive)\nsynced folder.\n\nIt's a single-person tool, built for my own freelancing workflow, but it doubles\nas a worked example of two things that are surprisingly fiddly to get right:\n\n- **Real-world tax \u0026 invoicing logic** — Bulgarian VAT treatments, gap-free legal\n  numbering, dual-language documents, and digital signing.\n- **Wiring an LLM to deterministic tools** — the language model orchestrates and\n  drafts free text, but never touches the money math.\n\n\u003e ⚠️ **Status: early development.** The roadmap is written; the code is being\n\u003e built bottom-up, test-first. See [DEVELOPMENT_PLAN.md](DEVELOPMENT_PLAN.md) for\n\u003e the full phased plan. Today the repo is mostly scaffolding — don't expect a\n\u003e working invoice generator yet.\n\n## What it does\n\nYou chat with it in your terminal:\n\n\u003e *\"Draft an invoice for ACME for May.\"*\n\nBehind that one sentence, Invoicely:\n\n1. Pulls your Toggl time entries for the date range and groups them into line\n   items (project + description → hours).\n2. Translates the line descriptions EN → BG via DeepL (you can edit the result).\n3. Looks up the right rates and legally-required VAT wording from your past\n   contracts and invoices (a small RAG index over your own documents).\n4. Computes VAT, totals, and any early-payment discount — in plain, tested\n   Python, never by the LLM.\n5. Shows you the actual computed invoice for confirmation.\n6. On your OK, allocates the next legal invoice number, renders a dual-language\n   PDF, digitally signs it, and saves both the PDF and a human-readable YAML\n   record to your Proton Drive folder.\n\nPlanned features beyond the MVP: client-signed timesheets via Skribble, Revolut\npayment reconciliation, expense \u0026 profitability tracking, and legally-correct\ninvoice cancellation \u0026 reissue.\n\n## Usage\n\n```bash\nuv run python main.py       # run the app (thin shim -\u003e invoicely.cli)\ninvoicely doctor            # environment / health smoke test\ninvoicely chat              # the terminal chat interface\ninvoicely reindex           # rebuild the RAG index over contracts \u0026 invoices\n```\n\n### Configuration\n\nSecrets (API keys, signing-key password) live in a repo-local `.env`\n(gitignored). Your business data — company legal info and per-client settings —\nlives in the synced Drive folder so it travels with your invoices across\nmachines. The signing `.pfx` certificate is kept **outside** the synced folder.\n\nThe data folder location is set via `INVOICELY_DATA_DIR` (default\n`~/ProtonDrive/Invoicely/`) and holds `config/`, `timesheets/`, `invoices/`,\n`contracts/`, `rag/`, `payments/`, `expenses/`, and `history/`.\n\n## Development\n\nPython 3.13, managed with [`uv`](https://docs.astral.sh/uv/). The project is built\ntest-first and human-gated: for each step, the test suite is written and reviewed\n*before* any implementation, and the accumulated suite is the safety net for later\nrefactoring. The full workflow and roadmap are in\n[DEVELOPMENT_PLAN.md](DEVELOPMENT_PLAN.md).\n\n```bash\nuv run pytest               # run tests\nuv run ruff check .         # lint\nuv run mypy src             # type-check\nuv add \u003cpackage\u003e            # add a dependency\n```\n\nIntegrations are tested against recorded fixtures, never live APIs, and tests\nalways run against a throwaway temp data directory.\n\n## License\n\nReleased under the [MIT License](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftitaniumcoder%2Finvoicely","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftitaniumcoder%2Finvoicely","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftitaniumcoder%2Finvoicely/lists"}