EN · RU

Technical Reference

Русский · User Guide · OKTMO

Contents

• Address Parsing
• Slots
• Matching Passes
• Settings
• Sources
• Run Artifacts
• Result Formatting
• Console Command
• Project Layout

How address parsing works, the slots, the matching passes, the configuration files, and the run artifacts.

Address Parsing

A raw address string is broken into components. The order matters: first the trailing building number is cut off, then the type and name of the street or territory are determined, then the settlement and the administrative unit above it.

What Is Recognised

Street types. улица, переулок, проспект, бульвар, тракт, шоссе, тупик, проезд, аллея, линия, набережная, площадь, квартал, микрорайон, километр, автодорога — with all the usual abbreviations (ул., пер., пр-т, б-р, наб., мкр.).

Territory types. тер., территория, СНТ, ДНТ, ТСН.

Settlement types. город, посёлок, деревня, село, слобода, станица, станция, хутор, улус, местечко, кишлак, аул, аал, арбан, починок, выселок, заимка, кордон, маяк, погост, слободка, усадьба, лесоучасток, метеостанция, разъезд. Railway forms are parsed separately: п. ж/д ст., ж/д остановочный пункт, ж/д блокпост, ж/д будка, ж/д ветка, ж/д казарма, ж/д платформа, ж/д площадка, ж/д путевой пост, рзд.. Compact forms гп, рп, кп, дп, пгт, нп are understood with and without dots.

Building number. The trailing part is split into a base and modifiers: 10, 10а, 10/2, 10к2, 10 корп. 2, 10 стр. 1, 10 литера А. The base is the number; the modifiers are everything else, brought to one form.

The Key Rule About Building Numbers

Building modifiers can never be collapsed into a bare number. 10к2 does not take 10, and 10 does not take 10к2 — neither on a strict pass nor on a relaxed one. The looseness of a pass concerns the spelling of the street, not blocks and letters.

Slots

A slot is one named component of an address. The address line is assembled from the enabled slots; in decomposed form each slot becomes a column.

Address Line Slots

Technical Slots

Defaults

The default assembly order of the address line is the order of the address line slots in the table above, top to bottom.

Every slot is enabled by default except microdistrict: in Russian addresses a microdistrict or quarter more often duplicates the street than complements it. The microdistrict column still remains — only the value is excluded from the line.

Slot column headers are written in full or short form, chosen on the reference processing screen.

Matching Passes

The matching engine is Ultimate_GT_Aligner. For each address column a candidate pool is built, and the reference rows take their pairs out of it.

A matched pair is removed from the pool immediately. One candidate cannot be handed out twice, and a pass that ran earlier is never overridden by a later one.

The passes run in strictly increasing looseness.

Precise passes are 0, 1, 2, 2C, 3, and 4. Relaxed are 2R and 5. The log summary separates them into their own lines.

Weights on the Fuzzy Passes

At equal street name similarity a candidate receives bonuses:

• matching building number — plus 50;
• matching territory — plus 30;
• matching building modifiers (pass 5) — plus 20;
• matching OKTMO territorial context — a bonus from the search scope profile.

A pair with incompatible territory codes is discarded before weights are counted.

Rows Without a Street

When a reference row has a building number but no street, comparing names approximately is meaningless. Such rows look for a candidate with the same building number, modifiers, and street numbers, and pick the best one by territorial weights.

Settings

config/project.yaml

address_aligner:
  city: "тюмень"              # city removed from keys during normalization
  ground_truth_column: "B"    # reference column; "" = auto-detect
  target_columns: "C,D"       # address columns; "" = auto
  companion_mode: "auto"      # auto | none | left | right | between
  max_auto_align_columns: 5   # how many columns to take on the right in auto mode

safety:
  cleanup_managed_workspace_only: true   # clean only project folders
  never_delete_original_inputs: true     # never delete original sources

Values from the window take priority over the file: an empty field in the window means "take from settings or detect automatically", a filled one overrides.

config/window_settings.json

The window's settings: its size, the language (ru | en), the theme (dark, codedark, vault, light), the font size and the width of the right column. The window writes the file itself; delete it to return to the defaults (Russian, the Code Dark theme). At start the source and the target are always the project's input and output: the earlier choice is not remembered, the history of paths is kept apart.

Other Configuration Files

tool_manifest.yaml is what the window is built from. Each operation is described by a title, a description, a set of fields, and a reference to a service-layer function. Both languages live in the same file as label / label_ru pairs. The window knows no operation by name: what to draw is said by the keys of the manifest and by the layout window_layout.yaml. Every operation of the manifest must stand in the layout — the tests and the self-check of the window verify it.

Sources

Supported: .xlsx, .docx, .odt, .txt, .csv, .md, .markdown, and .pdf with a text layer. A PDF without a text layer is not recognised — that is not this program's job.

Legacy .doc and .xls are handled only after conversion by a separate command.

Office temporary files (~$*) are skipped and removed during input validation.

Two-Level Headers

A row that carries no data values and sits under a horizontally merged parent header counts as a sub-header row. Its values are joined to the parent headers, and the row itself does not reach the data.

A column headed "Проектная мощность, мест" over "по корпусам" becomes "Проектная мощность, мест по корпусам" instead of an unnamed column_5.

Run Artifacts

Results

Names carry a YYYYMMDD_HHMMSS timestamp.

Reports in report/

Some operations additionally write <result name>.summary.json next to the workbook.

Audit Sheets

Moving columns by address adds an AUDIT_ADDRESS_JOIN sheet to the result. Address collection writes a rejected sheet when that option is on.

Result Formatting

Result workbooks go through post-processing: column widths are fitted to the content, long text wraps, row heights grow, and status columns get colour fill.

This is not cosmetics: without it every export has to be tidied by hand, and a row with a long address cannot be read in a narrow column.

Console Command

Whatever a button of the window does, the console command address_cli.cmd does too: the window is its "face" and has no way of its own to run an operation. An operation runs with the same field defaults and the same rules, so a run from the command line gives the same workbook as a run from the window.

An ordinary line of output goes to the journal. A line that begins with ::address:: is a service one and carries JSON: where the operation's journal is written, the share of the work done, the live line of a long stage, the outcome. The outcome of an operation is the --result file; stopping is the --cancel-file: the operation sees it and ends at the nearest safe point. Exit codes: 0 — done, 1 — the operation failed, 2 — a wrong call, 130 — stopped.

The rules that assemble the parameters of a run (the defaults, the conditions for showing a field, the order of the slots, the reset of the normalization fields in the "fast" mode, values outside a list) live in one place — system_core/core/operation_model.py — and the tests hold them.

Project Layout

A detailed file map is in tools/PROJECT_FILES_GUIDE_EN.md.