4 ms·

IRS open sources its fact graph

341 points by ronbenton 1y ago

expectation876 1y ago
[flagged]
ok123456 1y ago
Why would I want to use this over Prolog/Datalog?
- NoahZuniga 1y ago
  Because prolog/datalog don't offer a list of questions that you can ask based on context to calculate someone's US taxes.
  - ok123456 1y ago
    That's the database you consult(). Doing income taxes is well-suited to traditional logic programming.
    - akerl_ 1y ago
      This is a bit like asking "why would I use my car's schematics instead of a wrench". This is the rules engine's details. You could use it to build the logic and traversal in whatever language you like.
      - nerdponx 1y ago
        I think they're asking why you would build a rules engine and fact graph instead of "just" encoding it in Datalog.
tallowen 1y ago
It's nice to see an open sourced implementation of the US tax code! This was part of the IRS Direct File codebase that allowed people to file their taxes for free, directly with the IRS. It was canceled earlier this year by the Trump administration. It looks like the Fact Graph was already opensourced a couple months ago and that version of the factgraph lives here: https://github.com/IRS-Public/direct-file/tree/main/direct-file/fact-graph-scala https://github.com/IRS-Public/direct-file/tree/main/direct-f... I'm curious why a second repository was created for this.
- ronbenton 1y ago
  I wonder too. Perhaps the intent is for it to be standalone for general usage and not just as a part of the direct file project?
  - Twisol 1y ago
    Seems so, according to this file: https://github.com/IRS-Public/fact-graph/blob/main/docs/from-3.0-to-3.1.md https://github.com/IRS-Public/fact-graph/blob/main/docs/from... > The main changes are: [...] converting the fact-graph to a standalone library [...]
- infotainment 1y ago
  I'm still disappointed that they got rid of Direct File, such a promising start...
  - ronbenton 1y ago
    Big W for the tax lobby, big L for the rest of us
  - beej71 1y ago
    I'm far beyond disappointed for that. I'm fucking pissed. Such stupid politicking that makes all of our lives shittier.
    - thegreatpeter 1y ago
      https://directfile.irs.gov https://directfile.irs.gov ??
      - CamperBob2 1y ago
        Did you try actually using it?
      - beej71 1y ago
        "You’ve heard of Direct File, that’s gone. Big beautiful Billy wiped that out." --Internal Revenue Service Commissioner Bill Long, July 28, 2025
aliljet 1y ago
I wonder how this can be used with an LLM to provide interesting tax advice? I'd love to regularly ask questions of the tax code...
- ronbenton 1y ago
  Makes me wonder if someone has already trained a model on the tax code. Would be interesting for sure.
  - astrange 1y ago
    Model training data already contains all the text there is[0], so they can already answer questions like this (especially with web search), but they aren't good at tax calculations. https://arxiv.org/abs/2507.16126v1 https://arxiv.org/abs/2507.16126v1 [0] but it's quite possible the conversion from HTML to text is bad
    - kevin_thibedeau 1y ago
      The problem is that the text of US tax code isn't enough to know the correct action to take. The IRS has semi-formal policies based on how it has chosen to interpret the statutes. There are areas of gray that they don't clearly specify. Some of this is in supplementary publications but it still has subjective elements. One example is that settlements for "serious injuries" are regarded as non-taxable income. What constitutes serious is a squishy concept.
      - cco 1y ago
        Yeah you'd have to pull in a lot of case law and perform a lot of fine tuning on expert tax advice (you'd probably have to create this training data). Would be neat (and still legally fraught!).
    - TZubiri 1y ago
      You can technically use the language model as a data model. That was the quick hack that started it all, autocomplete on a question produces the answer, yes. However it's clear that we are moving towards separating the data and the language model. Even base chatgpt is given Search Tools and python Tools instead of producing them by text, the tool call itself may be generated by the model though. You can for sure use a pure LLM to ask it questions about tax code, but we'll probably see specific tools that only contain canon law and kosher case law, and sources it properly. Y'know instead of halucinating
jauntywundrkind 1y ago
This was such a fun neat part of the Direct File code drop 5 months ago. https://news.ycombinator.com/item?id=44131901 https://news.ycombinator.com/item?id=44131901 In particular there's a pretty nice inline tutorial that's still there in that release: https://github.com/IRS-Public/direct-file/blob/main/direct-file/fact-graph-scala/shared/src/main/scala/_tutorial/01_introduction.worksheet.sc https://github.com/IRS-Public/direct-file/blob/main/direct-f...
bickfordb 1y ago
Surprised to learn we still have an IRS
alberth 1y ago
> As a work of the United States Government, this project is in the public domain within the United States. What does it mean for the license to say "within the US"? Does this mean this software cannot be used outside the US?
- ronbenton 1y ago
  Good question. Copyright laws are country-specific, right? So perhaps it is just trying to be clear that there is no license being asserted outside of the US.
  - dragonwriter 1y ago
    Licenses are offered or granted (they are permissions from the copyright holder), not asserted.
- deleted 1y ago
  [deleted]
- dragonwriter 1y ago
  > What does it mean for the license to say "within the US"? It means exactly what it says; you have to read the whole thing (or at least the two sentences before the CC 1.0 Universal text, which is the operative mechanism by which the second sentence is effected), not a fraction of the first sentence. > Does this mean this software cannot be used outside the US? No. The license explains two things: (1) Without any license, this is automatically public domain in the US because it is a federal government work. (2) The federal government (as the owner of the copyright at creation outside the United States, at least anywhere that applies the common rules underlying the Berne Convention) waives copyright worldwide, and does so via the CC 1.0 Universal declaration (the text of which is then included.) So, it is, to the extent that this is legally possible, copyright-free globally.
- jandrewrogers 1y ago
  Some countries don't recognize the concept of Public Domain works. In the US, many government works are Public Domain as a matter of law. This creates complications internationally in those countries that don't recognize the legitimacy of Public Domain as a legal concept. Nonetheless, the US still wants to make it available internationally. To satisfy these conflicting requirements, the US government places it in the Public Domain in the US to satisfy US law. Additionally, they make it available internationally under a license that approximates the intent of Public Domain while still being recognized as a legally valid thing.
vineyardmike 1y ago
Am I being dumb or does this not actually contain the facts about the tax code? Is the /demo/all-facts file supposed to be the “real” facts? Are the XML fact files provided in another location? It’s pretty cool to see the way that the IRS handles defining and maintaining its tax calculations, but also a machine-readable tax code seems cool too.
- ronbenton 1y ago
  I believe the actual IRS tax code implementation is in a separate repo here: https://github.com/IRS-Public/direct-file https://github.com/IRS-Public/direct-file while the originally linked repo is the fact graph tooling decoupled from the tax implementation.
  - tyingq 1y ago
    Look like many of them are specifically the xml files here: https://github.com/IRS-Public/direct-file/tree/e0d5c84451cc52b72d20d04652e306bf4af1a43c/direct-file/backend/src/main/resources/tax https://github.com/IRS-Public/direct-file/tree/e0d5c84451cc5...
    - ronbenton 1y ago
      I was just reading through those! A bit dizzying
  - kumavis 1y ago
    specifically here https://github.com/IRS-Public/direct-file/tree/main/direct-file/backend/src/main/resources/tax https://github.com/IRS-Public/direct-file/tree/main/direct-f...
- MangoToupe 1y ago
  As far as I am aware, fact just means shared assumption. This seems entirely reasonable for a tax code.
- kmoser 1y ago
  From https://github.com/IRS-Public/fact-graph/blob/main/docs/fact-graph-3.1-adr.md https://github.com/IRS-Public/fact-graph/blob/main/docs/fact...: > Standardize Fact Dictionaries as a canonical format for declaratively modeling tax logic
rvitorper 1y ago
Scala mentioned
hedayet 1y ago
I’ve had frustrating experiences with TurboTax due to its overly complex interface, aggressive data collection under the guise of saving money (which it doesn’t deliver), and a convoluted pricing structure that rivals the IRS’s own complexity. I hope this initiative is good enough to enable domain experts and good people to build transparent, user-friendly alternatives to challenge TurboTax’s market grip. Has anyone encountered promising tools or approaches that tackle these pain points?
- willis936 1y ago
  DirectFile was quite good for the one year I was able to use it and addressed your concerns. Don't worry, that's since been taken care of. https://apnews.com/article/irs-direct-file-tax-returns-free-trump-4bb0bca02fab9b3d06ae6f45ac67b7ab https://apnews.com/article/irs-direct-file-tax-returns-free-...
  - j_bum 1y ago
    Just a heads up, your URL 404’s
    - willis936 1y ago
      Thanks. Fixed. I stripped what I thought was a tracker without testing.
      - Scoundreller 1y ago
        The fun part is you can change the text before what you thought was tracking to anything you want: http://apnews.com/article/apnews-declares-trump-stupid-4bb0bca02fab9b3d06ae6f45ac67b7ab http://apnews.com/article/apnews-declares-trump-stupid-4bb0b...
        culi 1y ago
        This is true about a lot of sites and I'll often remove the unimportant part when saving or sharing urls for brevity sake. E.g. https://apnews.com/article/4bb0bca02fab9b3d06ae6f45ac67b7ab https://apnews.com/article/4bb0bca02fab9b3d06ae6f45ac67b7ab This is true for most news websites as well as online shopping sites
hk1337 1y ago
My eyes read Scala but my brain was thinking Clojure, so I was a bit confused on why there weren’t any parentheses for the first couple of seconds looking at the source.
sciencesama 1y ago
How can this be used to hack to save money !!
flimflamm 1y ago
Are the rules versioned somehow? I didn't see that.
burnt-resistor 1y ago
If there weren't so many loopholes and tax dodges for billionaires and tax-preparer protectionism[0], whatever this is (ontology and/or knowledge graph, or something else) wouldn't even be necessary. 0: If Intuit (TurboTax) and others didn't keep lobbying to keep it so complicated, the IRS would be able to opt-out auto-calculate tax bills for income, estate, and corporate taxes automatically like many other advanced economies. PS: Federal shutdown day 16. IRS press office remains open. And most of the tax enforcement divisions were recently RIFed because it's too annoying for rich people to game the system to dodge taxes.

341 points by ronbenton 1y ago

expectation876 1y ago

[flagged]

ok123456 1y ago

Why would I want to use this over Prolog/Datalog?

NoahZuniga 1y ago
Because prolog/datalog don't offer a list of questions that you can ask based on context to calculate someone's US taxes.
- ok123456 1y ago
  That's the database you consult(). Doing income taxes is well-suited to traditional logic programming.
  - akerl_ 1y ago
    This is a bit like asking "why would I use my car's schematics instead of a wrench". This is the rules engine's details. You could use it to build the logic and traversal in whatever language you like.
    - nerdponx 1y ago
      I think they're asking why you would build a rules engine and fact graph instead of "just" encoding it in Datalog.

tallowen 1y ago

It's nice to see an open sourced implementation of the US tax code! This was part of the IRS Direct File codebase that allowed people to file their taxes for free, directly with the IRS. It was canceled earlier this year by the Trump administration. It looks like the Fact Graph was already opensourced a couple months ago and that version of the factgraph lives here: https://github.com/IRS-Public/direct-file/tree/main/direct-file/fact-graph-scala https://github.com/IRS-Public/direct-file/tree/main/direct-f... I'm curious why a second repository was created for this.

ronbenton 1y ago
I wonder too. Perhaps the intent is for it to be standalone for general usage and not just as a part of the direct file project?
- Twisol 1y ago
  Seems so, according to this file: https://github.com/IRS-Public/fact-graph/blob/main/docs/from-3.0-to-3.1.md https://github.com/IRS-Public/fact-graph/blob/main/docs/from... > The main changes are: [...] converting the fact-graph to a standalone library [...]
infotainment 1y ago
I'm still disappointed that they got rid of Direct File, such a promising start...
- ronbenton 1y ago
  Big W for the tax lobby, big L for the rest of us
- beej71 1y ago
  I'm far beyond disappointed for that. I'm fucking pissed. Such stupid politicking that makes all of our lives shittier.
  - thegreatpeter 1y ago
    https://directfile.irs.gov https://directfile.irs.gov ??
    - CamperBob2 1y ago
      Did you try actually using it?
    - beej71 1y ago
      "You’ve heard of Direct File, that’s gone. Big beautiful Billy wiped that out." --Internal Revenue Service Commissioner Bill Long, July 28, 2025

aliljet 1y ago

I wonder how this can be used with an LLM to provide interesting tax advice? I'd love to regularly ask questions of the tax code...

ronbenton 1y ago
Makes me wonder if someone has already trained a model on the tax code. Would be interesting for sure.
- astrange 1y ago
  Model training data already contains all the text there is[0], so they can already answer questions like this (especially with web search), but they aren't good at tax calculations. https://arxiv.org/abs/2507.16126v1 https://arxiv.org/abs/2507.16126v1 [0] but it's quite possible the conversion from HTML to text is bad
  - kevin_thibedeau 1y ago
    The problem is that the text of US tax code isn't enough to know the correct action to take. The IRS has semi-formal policies based on how it has chosen to interpret the statutes. There are areas of gray that they don't clearly specify. Some of this is in supplementary publications but it still has subjective elements. One example is that settlements for "serious injuries" are regarded as non-taxable income. What constitutes serious is a squishy concept.
    - cco 1y ago
      Yeah you'd have to pull in a lot of case law and perform a lot of fine tuning on expert tax advice (you'd probably have to create this training data). Would be neat (and still legally fraught!).
  - TZubiri 1y ago
    You can technically use the language model as a data model. That was the quick hack that started it all, autocomplete on a question produces the answer, yes. However it's clear that we are moving towards separating the data and the language model. Even base chatgpt is given Search Tools and python Tools instead of producing them by text, the tool call itself may be generated by the model though. You can for sure use a pure LLM to ask it questions about tax code, but we'll probably see specific tools that only contain canon law and kosher case law, and sources it properly. Y'know instead of halucinating

jauntywundrkind 1y ago

This was such a fun neat part of the Direct File code drop 5 months ago. https://news.ycombinator.com/item?id=44131901 https://news.ycombinator.com/item?id=44131901 In particular there's a pretty nice inline tutorial that's still there in that release: https://github.com/IRS-Public/direct-file/blob/main/direct-file/fact-graph-scala/shared/src/main/scala/_tutorial/01_introduction.worksheet.sc https://github.com/IRS-Public/direct-file/blob/main/direct-f...

bickfordb 1y ago

Surprised to learn we still have an IRS

alberth 1y ago

> As a work of the United States Government, this project is in the public domain within the United States. What does it mean for the license to say "within the US"? Does this mean this software cannot be used outside the US?

ronbenton 1y ago
Good question. Copyright laws are country-specific, right? So perhaps it is just trying to be clear that there is no license being asserted outside of the US.
- dragonwriter 1y ago
  Licenses are offered or granted (they are permissions from the copyright holder), not asserted.
deleted 1y ago
[deleted]
dragonwriter 1y ago
> What does it mean for the license to say "within the US"? It means exactly what it says; you have to read the whole thing (or at least the two sentences before the CC 1.0 Universal text, which is the operative mechanism by which the second sentence is effected), not a fraction of the first sentence. > Does this mean this software cannot be used outside the US? No. The license explains two things: (1) Without any license, this is automatically public domain in the US because it is a federal government work. (2) The federal government (as the owner of the copyright at creation outside the United States, at least anywhere that applies the common rules underlying the Berne Convention) waives copyright worldwide, and does so via the CC 1.0 Universal declaration (the text of which is then included.) So, it is, to the extent that this is legally possible, copyright-free globally.
jandrewrogers 1y ago
Some countries don't recognize the concept of Public Domain works. In the US, many government works are Public Domain as a matter of law. This creates complications internationally in those countries that don't recognize the legitimacy of Public Domain as a legal concept. Nonetheless, the US still wants to make it available internationally. To satisfy these conflicting requirements, the US government places it in the Public Domain in the US to satisfy US law. Additionally, they make it available internationally under a license that approximates the intent of Public Domain while still being recognized as a legally valid thing.

vineyardmike 1y ago

Am I being dumb or does this not actually contain the facts about the tax code? Is the /demo/all-facts file supposed to be the “real” facts? Are the XML fact files provided in another location? It’s pretty cool to see the way that the IRS handles defining and maintaining its tax calculations, but also a machine-readable tax code seems cool too.

ronbenton 1y ago
I believe the actual IRS tax code implementation is in a separate repo here: https://github.com/IRS-Public/direct-file https://github.com/IRS-Public/direct-file while the originally linked repo is the fact graph tooling decoupled from the tax implementation.
- tyingq 1y ago
  Look like many of them are specifically the xml files here: https://github.com/IRS-Public/direct-file/tree/e0d5c84451cc52b72d20d04652e306bf4af1a43c/direct-file/backend/src/main/resources/tax https://github.com/IRS-Public/direct-file/tree/e0d5c84451cc5...
  - ronbenton 1y ago
    I was just reading through those! A bit dizzying
- kumavis 1y ago
  specifically here https://github.com/IRS-Public/direct-file/tree/main/direct-file/backend/src/main/resources/tax https://github.com/IRS-Public/direct-file/tree/main/direct-f...
MangoToupe 1y ago
As far as I am aware, fact just means shared assumption. This seems entirely reasonable for a tax code.
kmoser 1y ago
From https://github.com/IRS-Public/fact-graph/blob/main/docs/fact-graph-3.1-adr.md https://github.com/IRS-Public/fact-graph/blob/main/docs/fact...: > Standardize Fact Dictionaries as a canonical format for declaratively modeling tax logic

rvitorper 1y ago

Scala mentioned

hedayet 1y ago

I’ve had frustrating experiences with TurboTax due to its overly complex interface, aggressive data collection under the guise of saving money (which it doesn’t deliver), and a convoluted pricing structure that rivals the IRS’s own complexity. I hope this initiative is good enough to enable domain experts and good people to build transparent, user-friendly alternatives to challenge TurboTax’s market grip. Has anyone encountered promising tools or approaches that tackle these pain points?

willis936 1y ago
DirectFile was quite good for the one year I was able to use it and addressed your concerns. Don't worry, that's since been taken care of. https://apnews.com/article/irs-direct-file-tax-returns-free-trump-4bb0bca02fab9b3d06ae6f45ac67b7ab https://apnews.com/article/irs-direct-file-tax-returns-free-...
- j_bum 1y ago
  Just a heads up, your URL 404’s
  - willis936 1y ago
    Thanks. Fixed. I stripped what I thought was a tracker without testing.
    - Scoundreller 1y ago
      The fun part is you can change the text before what you thought was tracking to anything you want: http://apnews.com/article/apnews-declares-trump-stupid-4bb0bca02fab9b3d06ae6f45ac67b7ab http://apnews.com/article/apnews-declares-trump-stupid-4bb0b...
      - culi 1y ago
        This is true about a lot of sites and I'll often remove the unimportant part when saving or sharing urls for brevity sake. E.g. https://apnews.com/article/4bb0bca02fab9b3d06ae6f45ac67b7ab https://apnews.com/article/4bb0bca02fab9b3d06ae6f45ac67b7ab This is true for most news websites as well as online shopping sites

hk1337 1y ago

My eyes read Scala but my brain was thinking Clojure, so I was a bit confused on why there weren’t any parentheses for the first couple of seconds looking at the source.

sciencesama 1y ago

How can this be used to hack to save money !!

flimflamm 1y ago

Are the rules versioned somehow? I didn't see that.

burnt-resistor 1y ago

If there weren't so many loopholes and tax dodges for billionaires and tax-preparer protectionism[0], whatever this is (ontology and/or knowledge graph, or something else) wouldn't even be necessary. 0: If Intuit (TurboTax) and others didn't keep lobbying to keep it so complicated, the IRS would be able to opt-out auto-calculate tax bills for income, estate, and corporate taxes automatically like many other advanced economies. PS: Federal shutdown day 16. IRS press office remains open. And most of the tax enforcement divisions were recently RIFed because it's too annoying for rich people to game the system to dodge taxes.