Zio.Utils

This bundle does not look at the repository. It finds numbers in a given text and returns them along with the words written next to each number. If Zio.text answers “Is this character the same as that one?” then this side answers “What numbers are written in this text?”

The usage is not predetermined

A 10% might be a value sought in one industry and discarded in another. In construction management, an operating profit of about 10 % is not progress, but in accounting it is that exact figure.

Therefore this function does not choose. It returns the number together with a label, and the caller decides what it means. If the engine chooses, it will match one industry but be wrong for all others.

Method	Description
Zio.utils.numbers(text, near=None, kinds=None)	Finds all numbers in the text and returns them as a list. If there are multiple lines, it looks line by line—because labels do not cross lines.
Zio.utils.number(text, near=None, kinds=None)	Returns the first of those. If none, returns None.

Zio.utils.numbers("진척률 : 약 90%")
# [{"kind": "percent", "value": 90, "label": "진척률", "about": True,
#   "raw": "90%", "line": "진척률 : 약 90%", "bracket": False}]

# 무엇을 진척으로 볼지는 **부르는 쪽이 말을 준다**
Zio.utils.numbers(worklog, near=["진척률", "진행률", "설치율"], kinds="percent")
# 90% ← "진척률"        16.4% ← "현장 설치율"
# (영업 이익 9% · 수신률 83.7% 는 걸러진다)

# 분량만
Zio.utils.numbers(worklog, kinds=["ratio", "count"])
# ratio  0 / 18     done=0  total=18
# count  18개점      value=18  unit="개점"

The eight categories to look for

kind	Example	Accompanying fields
percent	90%, 5 % 미만, 1.5%(±0.5%)	value, tolerance, bracket — If inside brackets, it is a deliberate notation by the author, so the strength of evidence differs.
ratio	0 / 18, 522대중 244대, 3분의 1	done, total, unit
count	18개점, 2,823점포, 522대	value, unit — Do not list units. Return the word that is attached verbatim.
money	579,000,000원, 약 1억 2천만원	value, unit, maybe
range	5~10%, 15~20%	low, high, unit — 15~20% is not just the single value 20 %.
nth	2차, 3회차, 제1장	index, unit
date	2026-08-21, 8월 7일, 2026년	value or year / month / day

Ambiguous cases are not chosen

8/7 is read as three possibilities — August 7, the 8th of 7 items, or 8 out of 7. Choosing one will silently fail for the other two, and from then on this function becomes unreliable.

Zio.utils.numbers("장비 발주(8/7)")
# [{"kind": "ratio", "done": 8, "total": 7, "label": "장비 발주",
#   "ambiguous": ["ratio", "nth", "date"],
#   "date": {"month": 8, "day": 7},
#   "nth":  {"index": 8, "of": 7}}]

# 헷갈릴 수 없는 것에는 ambiguous 가 없다
Zio.utils.numbers("부착( 0 / 18, 0%)")
# [{"kind": "ratio", "done": 0, "total": 18, ...}]   ← 0월은 없다

The parser returns all interpretations; the caller decides based on context. Amounts are similar — 2억 3천 is 200,003,000 but if the word pattern omits 만, it means 230,000,000. It provides both value and maybe.

Labels are the entirety of this bundle

Returning only numbers makes them applicable everywhere. The words written next to them allow the caller to infer meaning. Therefore, the rule for extracting labels is the most carefully crafted part of this bundle.

Original	Label	Rule
진척률 : 약 90%	진척률	: marks the left side as the label. It is opposite to other delimiters.
( 매출 194,132,600원 / 영업 이익 약 10% )	매출, 영업 이익	Parentheses and slashes separate fields. The comma in 194,132,600 does not split.
장비 발주(8/7)	장비 발주	If the parentheses contain only a number, look one token further left.
영업 이익 약 9%	영업 이익, about	Words like 약, 총, 최대 are removed from the label; their meaning remains.

Find generously, narrow with near

numbers() first finds everything. If some cannot be found, the caller has no way to handle them, but if many are found it can be narrowed by near and kinds. The words put into near are always supplied by the caller — putting a word like 진척률 inside the SDK makes it no longer a generic tool.