"""Write facts into a DKE store, from Python, for kinds you define yourself.

A DKE reasoning module supplies the reasoning; you supply the facts. This
package is the second half: it turns whatever you have read — a CSV, a
directory of source, an export from another system — into a DKE Python
program that records it, which you then submit to your store.

    from dke import FactProgram

    prog = FactProgram("inventory", source="warehouse-scan")
    prog.comment("Stock levels, read 2026-08-21.")
    prog.open()
    prog.table(
        "items",
        ['("widget", "Widget", 12)', '("sprocket", "Sprocket", 0)'],
        [prog.put("Item.s.label", "r[1]"),
         prog.put("Item.s.count", "r[2]")],
    )
    print(prog.render())

The output is a program you can read before you run it: every fact it would
record is a line you can see. Producing one talks to no network and spawns no
process, so it never needs your key: `import dke` and everything under
`dke.ingest` reach nothing that opens a socket, and the test suite asserts
that by reading the import graph and again by running it.

To send a program, reach for the client DELIBERATELY — it is the one module
here that talks to a network, and naming it is how you grant that:

    from dke.client import Client

    Client.from_env().run(prog.render()).raise_for_status()

WHY THIS IS A PACKAGE RATHER THAN AN EXAMPLE. The parts here are the ones
that are easy to get subtly wrong in the direction that does not announce
itself. A producer with a broken reader records nothing, which is loud. A
producer with a broken fact-writer records PLAUSIBLE facts: every query
still answers and the answers are wrong. Stable subjects, the revising
write verb, and string escaping are that class of problem, so they live in
one implementation rather than being restated in each producer.

`dke.ingest` holds the readers for one domain — source code, for the `code`
reasoning module. They are consumers of the layer above, and they are also
the worked example: your own reader supplies rows, and everything from the
rows onward is the same.
"""

from __future__ import annotations

from dke.factwriter import FactProgram, Ids, sanitize

__all__ = ["FactProgram", "Ids", "sanitize"]

# Must equal `version` in pyproject.toml — test_stubs.py asserts it. The two
# drifted at 0.1.0 -> 0.2.0 and the published release reported the old number.
__version__ = "0.5.1"