Metadata-Version: 2.5
Name: reg-meta
Version: 0.44.0
Summary: Search and query SCB registry metadata
Project-URL: Homepage, https://github.com/adamaltmejd/registry-research-toolkit
Project-URL: Repository, https://github.com/adamaltmejd/registry-research-toolkit
Project-URL: Issues, https://github.com/adamaltmejd/registry-research-toolkit/issues
Author-email: Adam Altmejd <adam@altmejd.se>
License: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.14
Requires-Dist: pydantic>=2.13.4
Requires-Dist: reg-schema>=3.0.0
Requires-Dist: zstandard>=0.23
Description-Content-Type: text/markdown

# reg_meta

Search and query SCB registry metadata from a local SQLite database. Designed for
programmatic use by LLM agents and tools; terminal use is secondary.

## Install

```bash
uv tool install reg-meta
reg-meta update      # downloads package + database (~400 MB compressed)
```

Maintainers can build from pinned prepared sources and checked curation with
`reg_meta_build`. See its [catalog
workflow](../reg_meta_build/README.md#catalog-workflow) for preparation, diagnostic
builds and strict publication. A build does not read loose CSV exports or modify
accepted inputs.

## Quick start

```bash
reg-meta search --query "kommun"                     # search all fields
reg-meta search --query "kommun" --field datacolumn  # column headers only
reg-meta get register LISA                           # register overview
reg-meta get schema --register LISA --years 2020     # columns for a year
reg-meta get groups LISA                             # folded variable families
reg-meta get varinfo "Kön"                           # variable details
reg-meta resolve --columns "Kon,FodelseAr"           # map column names
reg-meta docs search "disponibel inkomst"            # search documentation
```

Use `--help` on any command or subcommand for full flag documentation.

## Commands

### Query

  | Command               | Purpose                                                                                                        |
  | --------------------- | -------------------------------------------------------------------------------------------------------------- |
  | `search`              | Free-text search across registers, variables, columns, and value codes                                         |
  | `get register`        | Register overview with variants                                                                                |
  | `get schema`          | Column listing per register edition (validity window), with `--years`, `--columns-like`, `--summary`, `--flat` |
  | `get groups`          | Concept groups (folded variable families) with member facets; `--classifications` for vintage families         |
  | `get varinfo`         | Variable details with per-era `variable_state` history                                                         |
  | `get values`          | Value-set members for a variable, year-projected per `variable_state` era                                      |
  | `get datacolumns`     | All column aliases for a variable across registers                                                             |
  | `get coded-variables` | Variables with value sets, ranked by usage                                                                     |
  | `get diff`            | Schema changes between two years for a register                                                                |
  | `get lineage`         | Variable provenance across registers                                                                           |
  | `get availability`    | Temporal coverage for a variable or register                                                                   |
  | `get classification`  | Normalized code systems (SUN, SSYK, SNI, LKF, ...) with `--list`, `--codes`, `--variables`                     |
  | `resolve`             | Exact alias lookup for column names (batch)                                                                    |

### Documentation

  | Command       | Purpose                                                    |
  | ------------- | ---------------------------------------------------------- |
  | `docs search` | Full-text search over curated register documentation       |
  | `docs get`    | Retrieve full documentation for a variable or topic        |
  | `docs list`   | Browse available documentation by type, topic, or register |

### Maintenance

  | Command  | Purpose                                           |
  | -------- | ------------------------------------------------- |
  | `update` | Update package and database to the latest version |
  | `info`   | Database stats and import metadata                |

Build commands (`build-db`, `build-docs`, `seed-slugs`, `precheck-slugs`, `parse-sos`)
live in the separate `reg_meta_build` package. They are maintainer-only and require a
repo checkout (the wheel does not ship `curation/`, `fqid_slugs/`, `input_data/`, or
`docs/`); see the `reg_meta_build` README for the build flow.

## Output formats

All commands support `--format {table,list,json}`. Default is table, which auto-switches
to list for narrow results. Add `-v` for the full JSON envelope (contract version,
timing, database info).

Register arguments accept numeric IDs, exact names, or substring matches.

## Database

Stored at `~/.local/share/reg_meta/` by default. `--catalog NAME` selects its `NAME/`
subdirectory; `--catalog global` keeps the data root. `--db DIRECTORY` and
`$REG_META_DB` select an explicit artifact directory. `--catalog` and `--db` are
mutually exclusive. Explicit flags take precedence over the environment. Named steward
selections must match the artifact's steward identity.

A steward artifact defaults to `holdings` scope; a public catalog defaults to
`reference`. `search`, `get register`, `get schema` and `get availability` accept
`--scope holdings` or `--scope reference`. Reference scope reads the full selected
artifact. Holdings scope narrows bindings, states and periods to compiled possession;
requesting it on a public catalog is a configuration error.

```bash
reg-meta --catalog swecov --scope holdings get register scb/lisa
reg-meta --catalog swecov --scope reference search --query "inkomst"
reg-meta update --catalog swecov
reg-meta --catalog swecov order project_data.json -o order.json
```

Order reads compiled holdings from the selected artifact. Its provenance records the
artifact kind, steward and deterministic generation ID. A public catalog uses global
logical fallback. Documentation uses only the selected directory's sibling
`reg_meta_docs.db`; missing docs do not block metadata or order reads. Updating an
explicit directory requires an existing publishable artifact and preserves its identity.
Bootstrap an empty installation with a named or default update.

## Files

  | Path                                                                 | Purpose                                                |
  | -------------------------------------------------------------------- | ------------------------------------------------------ |
  | [DESIGN.md](DESIGN.md)                                               | Design rationale, constraints, and the object model    |
  | [../reg_meta_build/DESIGN.md](../reg_meta_build/DESIGN.md)           | Build pipeline and per-provider source-delivery shapes |
  | [../reg_meta_build/docs/SCHEMA.md](../reg_meta_build/docs/SCHEMA.md) | Documentation markdown file format                     |
  | `src/reg_meta/`                                                      | Package source                                         |
  | `tests/`                                                             | Test suite                                             |
