fava-nl2bql 0.1.0__tar.gz

fava_nl2bql-0.1.0/.gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

fava_nl2bql-0.1.0/.github/dependabot.yml

@@ -0,0 +1,31 @@
+version: 2
+updates:
+  - package-ecosystem: uv
+    directory: /
+    schedule:
+      interval: weekly
+    cooldown:
+      default-days: 7
+    labels:
+      - dependencies
+      - python:uv
+      - chore
+    groups:
+      python-dependencies:
+        update-types:
+          - minor
+          - patch
+
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: monthly
+    cooldown:
+      default-days: 7
+    labels:
+      - dependencies
+      - chore
+    groups:
+      github-actions:
+        patterns:
+          - "*"

fava_nl2bql-0.1.0/.github/pr-labeler.yml

@@ -0,0 +1,3 @@
+feature: feature/*
+bugfix: bugfix/*
+chore: chore/*

fava_nl2bql-0.1.0/.github/workflows/build-publish.yml

@@ -0,0 +1,133 @@
+name: Publish Python 🐍 distributions 📦 to PyPI and TestPyPI
+on:
+  push:
+    branches: [master]
+    tags: ["v*"]
+  pull_request:
+
+# a newer push to a pull request replaces the running checks, publishing is never interrupted
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+permissions: {}
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+        with:
+          python-version: "3.14"
+
+      - name: Install the project
+        run: uv sync --locked --dev
+
+      - name: Pre Commit
+        run: uv run pre-commit run --all-files
+
+      - name: Check dependencies
+        run: uv run deptry src
+
+      - name: Build documentation
+        run: uv run --locked --group docs sphinx-build -W --keep-going -b html docs "$RUNNER_TEMP/docs"
+
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    permissions:
+      contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install the project
+        run: uv sync --locked --dev
+
+      - name: Test
+        run: uv run pytest
+
+  build:
+    name: Build
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+        with:
+          python-version: "3.14"
+
+      - name: Build
+        run: uv build
+
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  # the publish jobs only get an OIDC token (trusted publishing), no repository content and no stored secrets
+  publish-testpypi:
+    name: Publish 📦 to TestPyPI
+    needs: [lint, test, build]
+    if: github.event_name == 'push' && github.ref == 'refs/heads/master'
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/fava-nl2bql
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: dist
+          path: dist/
+      - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+
+      - name: Publish distribution 📦 to Test PyPI
+        run: uv publish --trusted-publishing always --publish-url https://test.pypi.org/legacy/
+
+  publish-pypi:
+    name: Publish 📦 to PyPI
+    needs: [lint, test, build]
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    environment:
+      name: pypi
+      url: https://pypi.org/p/fava-nl2bql
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: dist
+          path: dist/
+      - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+
+      - name: Publish distribution 📦 to PyPI
+        run: uv publish --trusted-publishing always

fava_nl2bql-0.1.0/.github/workflows/pr-labeler.yml

@@ -0,0 +1,18 @@
+name: PR Labeler
+on:
+  pull_request:
+    types: [opened]
+
+permissions: {}
+
+jobs:
+  pr-labeler:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 5
+    permissions:
+      contents: read
+      pull-requests: write
+    steps:
+      - uses: TimonVS/pr-labeler-action@f9c084306ce8b3f488a8f3ee1ccedc6da131d1af # v5.0.0
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

fava_nl2bql-0.1.0/.github/workflows/release-drafter.yml

@@ -0,0 +1,20 @@
+name: Release Drafter
+
+on:
+  push:
+    branches:
+      - master
+
+permissions: {}
+
+jobs:
+  update_release_draft:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 5
+    permissions:
+      contents: write
+      pull-requests: read
+    steps:
+      - uses: release-drafter/release-drafter@34d80673e067bdc0c24568d3af899c216adcfaa9 # v7.7.0
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

fava_nl2bql-0.1.0/.gitignore

@@ -0,0 +1,37 @@
+# Temporary and binary files
+*~
+*.py[cod]
+*.so
+*.orig
+*.log
+__pycache__/
+.cache/
+.*.swp
+.DS_Store
+
+# Project files
+.idea
+.vscode
+
+# Package files
+*.egg
+*.eggs/
+.installed.cfg
+*.egg-info/
+
+# Unittest, coverage and type checking
+htmlcov/
+.coverage
+.tox
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Build and docs folder/files
+build/
+dist/
+docs/api/
+docs/_build/
+
+# Per-project virtualenvs
+.venv*/

fava_nl2bql-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,50 @@
+exclude: '^docs/conf.py'
+
+repos:
+- repo: https://github.com/pre-commit/pre-commit-hooks
+  rev: v6.0.0
+  hooks:
+  - id: trailing-whitespace
+  - id: check-added-large-files
+  - id: check-ast
+  - id: check-json
+  - id: check-merge-conflict
+  - id: check-xml
+  - id: check-yaml
+  - id: debug-statements
+  - id: end-of-file-fixer
+  - id: requirements-txt-fixer
+  - id: mixed-line-ending
+    args: ['--fix=auto']  # replace 'auto' with 'lf' to enforce Linux/Mac line endings or 'crlf' for Windows
+
+- repo: https://github.com/astral-sh/ruff-pre-commit
+  rev: v0.16.8
+  hooks:
+    - id: ruff-check
+    - id: ruff-format
+
+- repo: https://github.com/Lucas-C/pre-commit-hooks-markup
+  rev: v1.0.1
+  hooks:
+  - id: rst-linter
+    files: README.rst
+
+- repo: local
+  hooks:
+  - id: mypy
+    name: mypy
+    # runs in the project environment to see the types of the installed packages, mypy and its stubs are dev dependencies
+    entry: uv run --locked mypy src tests
+    language: system
+    types: [python]
+    pass_filenames: false
+
+- repo: https://github.com/astral-sh/uv-pre-commit
+  rev: 0.12.16
+  hooks:
+    - id: uv-lock
+
+- repo: https://github.com/zizmorcore/zizmor-pre-commit
+  rev: v1.30.1
+  hooks:
+    - id: zizmor

fava_nl2bql-0.1.0/.readthedocs.yaml

@@ -0,0 +1,22 @@
+# Read the Docs configuration file for Sphinx projects
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+sphinx:
+  configuration: docs/conf.py
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.14"
+  jobs:
+    pre_create_environment:
+        - asdf plugin add uv
+        - asdf install uv latest
+        - asdf global uv latest
+    create_environment:
+        - uv venv "${READTHEDOCS_VIRTUALENV_PATH}"
+    install:
+        - UV_PROJECT_ENVIRONMENT="${READTHEDOCS_VIRTUALENV_PATH}" uv sync --frozen --group docs

fava_nl2bql-0.1.0/CLAUDE.md

@@ -0,0 +1,16 @@
+# CLAUDE.md
+
+@CONTRIBUTING.md
+
+## Notes for Claude
+
+- Open pull requests and stop there, the maintainer reviews and merges them. Do not merge unless explicitly asked.
+- Run the checks from CONTRIBUTING.md before pushing, and `git add` new files first, `pre-commit --all-files` skips
+  untracked files.
+- Never put real financial data, credentials or personal details into the repository, commits, pull requests or
+  issues. Tests, fixtures and examples are synthetic.
+- Show that a test can fail: when fixing a bug, check that the new test fails without the fix.
+- When dependencies change, regenerate `uv.lock` with the uv version of the pre-commit hook and check that the lock
+  diff only contains what you intended.
+- Keep pull request descriptions factual: the problem, the change, how it was verified (including what could not be
+  verified before merging).

fava_nl2bql-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,86 @@
+# Contributing
+
+`fava-nl2bql` is a [Fava](https://beancount.github.io/fava/) extension that translates natural-language
+questions about a ledger into [BQL](https://beancount.github.io/docs/beancount_query_language.html) queries
+and runs them, published to PyPI. User documentation is in `docs/` (built with Sphinx, hosted on Read the Docs).
+
+## Layout
+
+| Path | Content |
+|---|---|
+| `src/fava_nl2bql/extension.py` | the `FavaExtensionBase` subclass Fava loads (report page, endpoints) |
+| `src/fava_nl2bql/translator.py` | natural language → BQL translation (the tuned model lives behind this) |
+| `src/fava_nl2bql/templates/` | Jinja template for the extension's report page |
+| `src/fava_nl2bql/FavaNl2Bql.js` | the extension's JS module (Fava loads `<ClassName>.js` next to the class) |
+| `tests/fava_nl2bql/` | tests, mirroring the layout of `src` |
+| `docs/` | user documentation, `docs/api` is generated at build time and git-ignored |
+
+## Setup
+
+```bash
+uv sync --locked --dev
+```
+
+Python 3.11 to 3.14 are supported and tested.
+
+## Checks
+
+CI runs the same commands, all of them have to pass:
+
+```bash
+uv run pre-commit run --all-files   # ruff, ruff format, mypy, uv-lock, zizmor, rst lint
+uv run deptry src                   # imports vs declared dependencies
+uv run pytest
+uv run --group docs sphinx-build -W --keep-going -b html docs docs/_build   # documentation without warnings
+uv build
+```
+
+Things that catch people out:
+
+- `pre-commit run --all-files` only looks at files tracked by git. `git add` new files before running it, otherwise
+  they are not checked (and CI then fails on them).
+- mypy runs in the project environment (a local pre-commit hook calling `uv run mypy`), so it checks against the types
+  of the installed packages. Stub packages (`types-*`) belong into the `dev` dependency group.
+- deptry fails for an import that is only available transitively and for a declared dependency that is not used.
+  Declare what you import in `pyproject.toml`, remove what you stop using.
+
+## Code
+
+- Type hints are required in `src` (mypy `disallow_untyped_defs`, tests are exempt).
+- ruff selects `E4, E7, E9, F, B, I, S113, T20, UP` (see `pyproject.toml`), `ruff format` decides the formatting.
+- Tests use synthetic ledgers and fixtures only: no real account numbers, balances or personal financial data,
+  not even anonymized ones.
+
+## Dependencies
+
+- `uv.lock` is committed. Regenerate it with the uv version of the `uv-lock` pre-commit hook (`rev` in
+  `.pre-commit-config.yaml`), a different uv version rewrites unrelated parts of the file:
+  `uvx --from uv==<rev> uv lock`.
+- Dependabot (`.github/dependabot.yml`) opens grouped PRs for minor and patch updates of Python packages weekly and
+  for GitHub Actions monthly. Major updates come as separate PRs.
+
+## Network
+
+- The only network call is `translator.py`'s call to a local Ollama server via the `ollama` package.
+  Always pass `timeout=` to `Client(...)` — a stalled server must not block the request forever.
+- Tests must not make real network calls: mock `fava_nl2bql.translator.Client` (see
+  `tests/fava_nl2bql/test_translator.py`).
+
+## Git and pull requests
+
+- Branch off `master`, named `feature/…`, `bugfix/…` or `chore/…` (snake_case after the prefix). The prefix labels
+  the PR (`.github/pr-labeler.yml`), and the label decides the category in the release notes (the shared
+  `release-drafter.yml` of [tarioch/.github](https://github.com/tarioch/.github)).
+- Commit subjects are imperative and start with a capital letter, the body explains why.
+- Changes go through pull requests into `master` and are merged with a merge commit.
+
+## CI and releases
+
+`.github/workflows/build-publish.yml` runs `lint`, `test` (matrix), `build`, and on pushes to `master` and version tags
+the publish jobs. Workflows use the least permissions they need, and every action is pinned to a commit SHA.
+
+- Every push to `master` publishes a development version to TestPyPI.
+- Release notes are drafted by release-drafter. Publishing the draft creates the tag `vX.Y.Z`, which publishes to PyPI.
+- Publishing uses PyPI trusted publishing (OIDC) from the GitHub environments `testpypi` and `pypi`, there are no
+  stored tokens.
+- The version is derived from the git tags (uv-dynamic-versioning), so CI checks out the full history (`fetch-depth: 0`).

fava_nl2bql-0.1.0/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Patrick Ruckstuhl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fava_nl2bql-0.1.0/MANIFEST.in

@@ -0,0 +1,2 @@
+prune .github
+exclude .gitignore

fava_nl2bql-0.1.0/PKG-INFO

@@ -0,0 +1,37 @@
+Metadata-Version: 2.5
+Name: fava-nl2bql
+Version: 0.1.0
+Summary: Fava extension: ask questions about your ledger in plain English, get BQL results
+Project-URL: Homepage, https://github.com/tarioch/fava-nl2bql
+Project-URL: Documentation, https://fava-nl2bql.rtfd.io
+Project-URL: Repository, https://github.com/tarioch/fava-nl2bql/
+Project-URL: Issues, https://github.com/tarioch/fava-nl2bql/issues
+Author-email: Patrick Ruckstuhl <patrick@ch.tario.org>
+License-Expression: MIT
+License-File: LICENSE.txt
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Framework :: Flask
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Office/Business :: Financial :: Accounting
+Requires-Python: >=3.11
+Requires-Dist: fava>=1.30
+Requires-Dist: ollama>=0.6
+Description-Content-Type: text/x-rst
+
+.. image:: https://img.shields.io/pypi/l/fava-nl2bql.svg
+   :target: https://pypi.python.org/pypi/fava-nl2bql
+.. image:: https://img.shields.io/pypi/v/fava-nl2bql.svg
+   :target: https://pypi.python.org/pypi/fava-nl2bql
+.. image:: https://readthedocs.org/projects/fava-nl2bql/badge
+   :target: https://fava-nl2bql.rtfd.io
+
+fava-nl2bql
+===========
+
+A `Fava <https://beancount.github.io/fava/>`__ extension that translates plain-English questions about
+your ledger into `BQL <https://beancount.github.io/docs/beancount_query_language.html>`__ queries and runs
+them, using a small tuned model instead of hand-written heuristics.
+
+This project is a work in progress. See the detailed `Documentation <https://fava-nl2bql.rtfd.io/>`__.

fava_nl2bql-0.1.0/README.rst

@@ -0,0 +1,15 @@
+.. image:: https://img.shields.io/pypi/l/fava-nl2bql.svg
+   :target: https://pypi.python.org/pypi/fava-nl2bql
+.. image:: https://img.shields.io/pypi/v/fava-nl2bql.svg
+   :target: https://pypi.python.org/pypi/fava-nl2bql
+.. image:: https://readthedocs.org/projects/fava-nl2bql/badge
+   :target: https://fava-nl2bql.rtfd.io
+
+fava-nl2bql
+===========
+
+A `Fava <https://beancount.github.io/fava/>`__ extension that translates plain-English questions about
+your ledger into `BQL <https://beancount.github.io/docs/beancount_query_language.html>`__ queries and runs
+them, using a small tuned model instead of hand-written heuristics.
+
+This project is a work in progress. See the detailed `Documentation <https://fava-nl2bql.rtfd.io/>`__.

fava_nl2bql-0.1.0/docs/conf.py

@@ -0,0 +1,106 @@
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+import os
+import sys
+import inspect
+import shutil
+
+# -- Path setup --------------------------------------------------------------
+
+__location__ = os.path.join(
+    os.getcwd(), os.path.dirname(inspect.getfile(inspect.currentframe()))
+)
+
+sys.path.insert(0, os.path.join(__location__, "../src"))
+
+# -- Run sphinx-apidoc -------------------------------------------------------
+# This hack is necessary since RTD does not issue `sphinx-apidoc` before running
+# `sphinx-build -b html . _build/html`.
+
+from sphinx.ext import apidoc
+
+output_dir = os.path.join(__location__, "api")
+module_dir = os.path.join(__location__, "../src/fava_nl2bql")
+try:
+    shutil.rmtree(output_dir)
+except FileNotFoundError:
+    pass
+
+try:
+    import sphinx
+
+    cmd_line = f"sphinx-apidoc --implicit-namespaces -f -o {output_dir} {module_dir}"
+    args = cmd_line.split(" ")[1:]
+    apidoc.main(args)
+except Exception as e:
+    print(f"Running `sphinx-apidoc` failed!\n{e}")
+
+# -- General configuration ---------------------------------------------------
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.todo",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.coverage",
+    "sphinx.ext.doctest",
+    "sphinx.ext.ifconfig",
+    "sphinx.ext.mathjax",
+    "sphinx.ext.napoleon",
+    "sphinx_rtd_theme",
+]
+
+templates_path = ["_templates"]
+source_suffix = ".rst"
+master_doc = "index"
+
+project = "fava-nl2bql"
+copyright = "2026, Patrick Ruckstuhl"
+
+version = ""
+release = ""
+
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", ".venv"]
+
+pygments_style = "sphinx"
+
+# -- Options for HTML output -------------------------------------------------
+
+html_theme = "sphinx_rtd_theme"
+html_theme_options = {}
+
+try:
+    from fava_nl2bql import __version__ as version
+except ImportError:
+    pass
+else:
+    release = version
+
+html_static_path = ["_static"]
+html_show_sphinx = False
+htmlhelp_basename = "fava-nl2bql-doc"
+
+# -- Options for LaTeX output ------------------------------------------------
+
+latex_elements = {}
+
+latex_documents = [
+    (
+        "index",
+        "user_guide.tex",
+        "fava-nl2bql Documentation",
+        "Patrick Ruckstuhl",
+        "manual",
+    )
+]
+
+# -- External mapping --------------------------------------------------------
+python_version = ".".join(map(str, sys.version_info[0:2]))
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/" + python_version, None),
+}

fava_nl2bql-0.1.0/docs/index.rst

@@ -0,0 +1,25 @@
+===========
+fava-nl2bql
+===========
+
+A `Fava <https://beancount.github.io/fava/>`__ extension that translates plain-English questions about your
+ledger into `BQL <https://beancount.github.io/docs/beancount_query_language.html>`__ queries and runs them.
+
+Contents
+========
+
+.. toctree::
+   :maxdepth: 3
+
+   Installation <installation>
+   Usage <usage>
+   License <license>
+   Module Reference <api/modules>
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

fava_nl2bql-0.1.0/docs/installation.rst

@@ -0,0 +1,17 @@
+Installation
+============
+
+As this is released on `PyPI <https://pypi.python.org/pypi/fava-nl2bql/>`__ you can install it with
+
+.. code-block:: console
+
+   pip install fava-nl2bql
+
+Then enable it in your beancount file:
+
+.. code-block:: text
+
+   2026-01-01 custom "fava-extension" "fava_nl2bql.extension"
+
+See :doc:`usage` for the prerequisites (a local Ollama instance with the translation model pulled)
+and the ``ollama_host``/``model`` config keys.

fava_nl2bql-0.1.0/docs/license.rst

@@ -0,0 +1,7 @@
+.. _license:
+
+=======
+License
+=======
+
+.. include:: ../LICENSE.txt