ihalent 0.1.0__tar.gz

ihalent-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,41 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python: ["3.10", "3.14"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python }}
+
+      - name: Install
+        run: uv sync --dev
+
+      - name: Lint
+        run: uv run ruff check src tests
+
+      - name: Types
+        run: uv run mypy src
+
+      - name: Tests
+        run: uv run pytest
+
+      - name: The bundled example must rebuild and analyze cleanly
+        shell: bash
+        run: |
+          uv run python examples/build_sample.py
+          # --json is ASCII by contract, so this is safe on any console code page;
+          # the negative-discount case must survive the round trip.
+          uv run ihalent overview examples/sample-awards.jsonl --json | grep -q '"min": -2.96'

ihalent-0.1.0/.gitignore

@@ -0,0 +1,22 @@
+# python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+
+# tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# editors / os
+.vscode/
+.idea/
+Thumbs.db
+.DS_Store
+
+# local award data (users collect their own; only the example ships)
+/awards.jsonl
+/bundle.json

ihalent-0.1.0/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+## 0.1.0 — 2026-07-17
+
+First public release.
+
+- Parse EKAP result notices (Sonuç İlanı) into structured `Award` records: İKN, estimate,
+  contract price, winner (with joint-venture members), bid counts, dates — deterministically,
+  with missing fields left `None` rather than guessed.
+- Analytics: firm profiles (folded across spelling variants), discount (kırım) distributions
+  grouped by authority / province / tender type, and competition stats including single-bid
+  share.
+- The coverage discipline: every statistic reports how many records it used and how many it
+  dropped for missing data; discounts are never computed from a missing estimate.
+- `ingest` from ihale-mcp / EKAP output (pure function, no network), plus `overview`, `firm`,
+  `discounts` and `parse` commands, each with a `--json` form.
+- Optional MCP server (`pip install 'ihalent[mcp]'`, `ihalent-mcp`) exposing the analytics as
+  agent tools over a dataset from `IHALENT_AWARDS`.
+- Worked example built from four real December-2025 awards across four authority types,
+  including a negative-discount emergency-procurement case and the code that structures them.
+- 44 tests over the exact JSON shapes EKAP and ihale-mcp emit.

ihalent-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,31 @@
+# Contributing
+
+Thanks for considering it. ihalent stays useful only if it stays honest about what it does
+and does not know, so a few rules protect that.
+
+## Ground rules
+
+- **The core is a pure function of its input.** No network calls, no signing keys, no live
+  scraping in `parse`, `analytics`, `ingest` or `store`. Collection is ihale-mcp's job.
+- **Never invent a number.** A missing field is `None`, not `0` or `""`. A statistic reports
+  its coverage. If a change would let a mean hide how many records lacked the value, it's the
+  wrong change.
+- **Parsing changes ship with a real notice.** The tests are built on the exact markdown EKAP
+  serves. If you handle a new notice variant, add the real (trimmed) notice that motivated it
+  to `tests/` so the parser is pinned to reality, not to a tidy invention.
+- **Company-name folding errs toward splitting, not merging.** Merging two real firms into one
+  row corrupts the analysis silently; showing two rows for one firm is visible and fixable.
+  New normalization rules need a test that they don't over-merge.
+
+## Mechanics
+
+```
+uv sync --dev
+uv run pytest
+uv run ruff check src tests
+uv run mypy src
+```
+
+All three must be clean; CI runs them on Linux and Windows. Keep PRs scoped to one change,
+and if you touch the parser or the example, re-run `python examples/build_sample.py` in the
+same PR so the committed sample matches the code.

ihalent-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mehmet Eren Gülmez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ihalent-0.1.0/PKG-INFO

@@ -0,0 +1,224 @@
+Metadata-Version: 2.4
+Name: ihalent
+Version: 0.1.0
+Summary: Turkish public-tender award intelligence: who won, for how much, at what discount, against how many bidders.
+Project-URL: Homepage, https://github.com/gulmezeren2-byte/ihalent
+Project-URL: Repository, https://github.com/gulmezeren2-byte/ihalent
+Project-URL: Issues, https://github.com/gulmezeren2-byte/ihalent/issues
+Project-URL: Changelog, https://github.com/gulmezeren2-byte/ihalent/blob/main/CHANGELOG.md
+Author: Mehmet Eren Gülmez
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,analytics,ekap,government-data,mcp,public-procurement,tenders,turkey
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: rich>=13.7
+Requires-Dist: typer>=0.12
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.2; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# ihalent
+
+**Turkish public-tender award intelligence: who won, for how much, at what discount, against how many bidders.**
+
+[![CI](https://github.com/gulmezeren2-byte/ihalent/actions/workflows/ci.yml/badge.svg)](https://github.com/gulmezeren2-byte/ihalent/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](pyproject.toml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+Every public tender in Turkey ends with a *Sonuç İlanı* — a result notice that states the
+estimate, the contract price, the winner, and how many firms bid. The notices are public.
+They are also one at a time, unstructured, and impossible to reason across: you cannot ask
+EKAP "what has this company won in the last two years" or "how far below estimate does this
+authority actually award." ihalent turns those notices into structured records and answers
+exactly those questions — firm histories, discount (kırım) distributions, and competition
+metrics — with every number traceable back to the notice it came from.
+
+```
+$ ihalent overview awards.jsonl
+
+Dataset overview
+  4 tenders: 4 awarded, 0 cancelled
+  total awarded value: 677.878.066,48 TL
+  Discount (kırım): mean 18.22%  median 20.99%  min -2.96%  max 33.87%
+  based on all 4 awards.
+  competition: 5.75 valid bids on average (median 4.0); 0.0% had a single valid bid
+  data gaps: 0 awards without an estimate, 0 without a bid count.
+```
+
+That is real output over four real December-2025 awards (in
+[`examples/`](examples/)). The `-2.96%` is not a bug: Istanbul University awarded a
+615-million-lira campus job at **2.96% above** its own estimate, through an emergency
+"pazarlık" procedure — a contract signed over the public estimate, which is precisely the
+kind of thing that should be easy to see and currently is not.
+
+## Why this exists
+
+I'm an industrial engineer and I work in construction. When our firm weighs a public
+tender, the questions that decide the bid are all about other people's history: how far
+below estimate does this authority award, how many firms usually show up, what has a given
+competitor been winning and at what price. All of that is public — it is sitting in tens of
+thousands of result notices on EKAP — and none of it is queryable. So everyone rebuilds a
+private, partial version of it by hand, in spreadsheets, badly.
+
+There is already an excellent tool for *reaching* this data:
+[saidsurucu/ihale-mcp](https://github.com/saidsurucu/ihale-mcp) solved authenticated EKAP
+access and hands you the notices. ihalent is the layer above it — the one that turns a pile
+of notices into an answer. It does not re-scrape EKAP; it structures what you have collected
+and does the analytics that don't exist yet.
+
+## What it answers
+
+**A firm's history** — every award across the dataset, folded across spelling variants:
+
+```
+$ ihalent firm awards.jsonl "ÖZDEN YEL"
+
+ÖZDEN YEL
+  wins: 1   joint ventures: 1   total contract value: 19.709.997,40 TL
+  Discount (kırım): mean 33.87%
+  top awarding authorities:
+      1x  DSİ 14. Bölge Müdürlüğü
+```
+
+**Where the discounts are** — grouped and sorted, highest first:
+
+```
+$ ihalent discounts awards.jsonl --by authority
+
+Mean discount by authority
+  DSİ 14. Bölge Müdürlüğü            33.87%   1/1
+  Esenler Belediyesi                21.99%   1/1
+  Ağrı İl Özel İdaresi              19.99%   1/1
+  İstanbul Üniversitesi-Cerrahpaşa  -2.96%   1/1
+```
+
+**Competition** — how many valid bids show up, and how often exactly one does (a single-bid
+award is a flag procurement watchdogs care about). It's in the overview above.
+
+## The one rule
+
+**A number is never shown without the ground it stands on.** A mean discount always comes
+with "over how many awards, and how many were dropped for a missing estimate." A firm's
+total contract value says so when some of its wins had no published price, so you read it as
+a floor, not the full figure. A discount is `None`, never `0`, when the estimate wasn't
+published — ihalent does not invent the numbers the government didn't print. Half the value
+of a tool like this is refusing to guess.
+
+## Install
+
+```
+pip install git+https://github.com/gulmezeren2-byte/ihalent
+```
+
+A PyPI release (`pip install ihalent`) follows once the first users have kicked the tires.
+
+## The workflow
+
+ihalent reads a JSONL file of awards. You produce it by collecting result notices — the
+easy path is ihale-mcp — and letting ihalent structure them:
+
+```
+# 1. collect: with ihale-mcp connected to your agent, save what its
+#    get_tender_announcements returns (one or many tenders) to bundle.json
+
+# 2. structure:
+ihalent ingest bundle.json -o awards.jsonl
+
+# 3. ask:
+ihalent overview  awards.jsonl
+ihalent firm      awards.jsonl "ACME İNŞAAT"
+ihalent discounts awards.jsonl --by province --min 5
+```
+
+Every command takes `--json` for pipelines and agents. Or skip collection and try the
+bundled example directly:
+
+```
+git clone https://github.com/gulmezeren2-byte/ihalent && cd ihalent
+python examples/build_sample.py       # parses the real notices in examples/notices/
+ihalent overview examples/sample-awards.jsonl
+```
+
+## Commands
+
+| command | what it does |
+|---|---|
+| `ihalent overview AWARDS` | value, discount, competition and the data gaps of a dataset |
+| `ihalent firm AWARDS "NAME"` | one company's wins, total value, discount, and where it wins |
+| `ihalent discounts AWARDS --by X` | mean/median discount grouped by authority, province or tender_type |
+| `ihalent parse NOTICE.md` | one result notice → structured JSON |
+| `ihalent ingest BUNDLE.json` | collected ihale-mcp/EKAP output → awards JSONL |
+
+## Using it with AI agents
+
+The result notice is unstructured text; the interesting questions are aggregate. That is an
+awkward fit for an agent working notice-by-notice, and a natural fit for a tool: `--json`
+output with stable fields, an exit code that means something, and a firm-name match that
+folds spelling variants so an agent doesn't have to.
+
+There is a native **MCP server** (`pip install 'ihalent[mcp]'`) that exposes the analytics
+as tools — `overview`, `firm`, `discounts`, `parse_notice`, `ingest_bundle` — over a dataset
+you point it at:
+
+```
+IHALENT_AWARDS=awards.jsonl ihalent-mcp
+```
+
+Pair it with ihale-mcp and an agent can collect notices and reason across them in one
+session: ihale-mcp fetches, ihalent structures and aggregates. The Python API
+(`ihalent.ingest_bundle`, `ihalent.analytics.firm_profile`) is three calls deep if you'd
+rather script it.
+
+## Scope, honestly
+
+- **This is analytics, not a scraper.** Collection is ihale-mcp's job (it does it well);
+  ihalent deliberately owns the layer above and stays a pure function of the data you give
+  it — no network, no signing keys, nothing that breaks when EKAP rotates a header.
+- **Company-name folding is conservative on purpose.** It merges legal-form suffixes and
+  Turkish spelling variants, and it would rather show two rows for one firm than one row for
+  two — so `firm` reports how many distinct spellings a query matched, and warns you if that
+  is more than one.
+- **The parser tracks one document: the result notice.** Bid-level detail (who else bid, at
+  what price) is not in the notice and so is not here. Discount is the estimate-to-contract
+  gap, which the notice does carry.
+- **Award values are nominal lira, as printed.** Comparing 2023 and 2026 contracts is your
+  analysis to make with the dates in hand; ihalent does not silently inflation-adjust.
+
+## What ihalent is not
+
+It is not a replacement for [ihale-mcp](https://github.com/saidsurucu/ihale-mcp) — it sits
+on top of it. It is not a live dashboard or a paid tender-alert service; it is a library and
+a CLI you point at data you control. And it does not redistribute a dataset: it ships the
+handful of real notices in `examples/` and the code to structure your own.
+
+## A note on the data
+
+Public-tender results are public information, published by the state for public scrutiny.
+ihalent structures what EKAP already discloses. Company names that appear are legal entities
+in their public commercial capacity, not private individuals.
+
+## How this project is built
+
+I designed the model and the analytics and I review every line; I use AI agents (Claude
+Code) heavily for implementation speed, and the commit trailers say so. The contract is the
+tests — 44 of them, built on the exact JSON shapes EKAP and ihale-mcp emit, including a
+result notice with a negative discount and a cancelled tender. They don't care who typed
+them.
+
+## License
+
+[MIT](LICENSE) — Mehmet Eren Gülmez

ihalent-0.1.0/README.md

@@ -0,0 +1,191 @@
+# ihalent
+
+**Turkish public-tender award intelligence: who won, for how much, at what discount, against how many bidders.**
+
+[![CI](https://github.com/gulmezeren2-byte/ihalent/actions/workflows/ci.yml/badge.svg)](https://github.com/gulmezeren2-byte/ihalent/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](pyproject.toml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+Every public tender in Turkey ends with a *Sonuç İlanı* — a result notice that states the
+estimate, the contract price, the winner, and how many firms bid. The notices are public.
+They are also one at a time, unstructured, and impossible to reason across: you cannot ask
+EKAP "what has this company won in the last two years" or "how far below estimate does this
+authority actually award." ihalent turns those notices into structured records and answers
+exactly those questions — firm histories, discount (kırım) distributions, and competition
+metrics — with every number traceable back to the notice it came from.
+
+```
+$ ihalent overview awards.jsonl
+
+Dataset overview
+  4 tenders: 4 awarded, 0 cancelled
+  total awarded value: 677.878.066,48 TL
+  Discount (kırım): mean 18.22%  median 20.99%  min -2.96%  max 33.87%
+  based on all 4 awards.
+  competition: 5.75 valid bids on average (median 4.0); 0.0% had a single valid bid
+  data gaps: 0 awards without an estimate, 0 without a bid count.
+```
+
+That is real output over four real December-2025 awards (in
+[`examples/`](examples/)). The `-2.96%` is not a bug: Istanbul University awarded a
+615-million-lira campus job at **2.96% above** its own estimate, through an emergency
+"pazarlık" procedure — a contract signed over the public estimate, which is precisely the
+kind of thing that should be easy to see and currently is not.
+
+## Why this exists
+
+I'm an industrial engineer and I work in construction. When our firm weighs a public
+tender, the questions that decide the bid are all about other people's history: how far
+below estimate does this authority award, how many firms usually show up, what has a given
+competitor been winning and at what price. All of that is public — it is sitting in tens of
+thousands of result notices on EKAP — and none of it is queryable. So everyone rebuilds a
+private, partial version of it by hand, in spreadsheets, badly.
+
+There is already an excellent tool for *reaching* this data:
+[saidsurucu/ihale-mcp](https://github.com/saidsurucu/ihale-mcp) solved authenticated EKAP
+access and hands you the notices. ihalent is the layer above it — the one that turns a pile
+of notices into an answer. It does not re-scrape EKAP; it structures what you have collected
+and does the analytics that don't exist yet.
+
+## What it answers
+
+**A firm's history** — every award across the dataset, folded across spelling variants:
+
+```
+$ ihalent firm awards.jsonl "ÖZDEN YEL"
+
+ÖZDEN YEL
+  wins: 1   joint ventures: 1   total contract value: 19.709.997,40 TL
+  Discount (kırım): mean 33.87%
+  top awarding authorities:
+      1x  DSİ 14. Bölge Müdürlüğü
+```
+
+**Where the discounts are** — grouped and sorted, highest first:
+
+```
+$ ihalent discounts awards.jsonl --by authority
+
+Mean discount by authority
+  DSİ 14. Bölge Müdürlüğü            33.87%   1/1
+  Esenler Belediyesi                21.99%   1/1
+  Ağrı İl Özel İdaresi              19.99%   1/1
+  İstanbul Üniversitesi-Cerrahpaşa  -2.96%   1/1
+```
+
+**Competition** — how many valid bids show up, and how often exactly one does (a single-bid
+award is a flag procurement watchdogs care about). It's in the overview above.
+
+## The one rule
+
+**A number is never shown without the ground it stands on.** A mean discount always comes
+with "over how many awards, and how many were dropped for a missing estimate." A firm's
+total contract value says so when some of its wins had no published price, so you read it as
+a floor, not the full figure. A discount is `None`, never `0`, when the estimate wasn't
+published — ihalent does not invent the numbers the government didn't print. Half the value
+of a tool like this is refusing to guess.
+
+## Install
+
+```
+pip install git+https://github.com/gulmezeren2-byte/ihalent
+```
+
+A PyPI release (`pip install ihalent`) follows once the first users have kicked the tires.
+
+## The workflow
+
+ihalent reads a JSONL file of awards. You produce it by collecting result notices — the
+easy path is ihale-mcp — and letting ihalent structure them:
+
+```
+# 1. collect: with ihale-mcp connected to your agent, save what its
+#    get_tender_announcements returns (one or many tenders) to bundle.json
+
+# 2. structure:
+ihalent ingest bundle.json -o awards.jsonl
+
+# 3. ask:
+ihalent overview  awards.jsonl
+ihalent firm      awards.jsonl "ACME İNŞAAT"
+ihalent discounts awards.jsonl --by province --min 5
+```
+
+Every command takes `--json` for pipelines and agents. Or skip collection and try the
+bundled example directly:
+
+```
+git clone https://github.com/gulmezeren2-byte/ihalent && cd ihalent
+python examples/build_sample.py       # parses the real notices in examples/notices/
+ihalent overview examples/sample-awards.jsonl
+```
+
+## Commands
+
+| command | what it does |
+|---|---|
+| `ihalent overview AWARDS` | value, discount, competition and the data gaps of a dataset |
+| `ihalent firm AWARDS "NAME"` | one company's wins, total value, discount, and where it wins |
+| `ihalent discounts AWARDS --by X` | mean/median discount grouped by authority, province or tender_type |
+| `ihalent parse NOTICE.md` | one result notice → structured JSON |
+| `ihalent ingest BUNDLE.json` | collected ihale-mcp/EKAP output → awards JSONL |
+
+## Using it with AI agents
+
+The result notice is unstructured text; the interesting questions are aggregate. That is an
+awkward fit for an agent working notice-by-notice, and a natural fit for a tool: `--json`
+output with stable fields, an exit code that means something, and a firm-name match that
+folds spelling variants so an agent doesn't have to.
+
+There is a native **MCP server** (`pip install 'ihalent[mcp]'`) that exposes the analytics
+as tools — `overview`, `firm`, `discounts`, `parse_notice`, `ingest_bundle` — over a dataset
+you point it at:
+
+```
+IHALENT_AWARDS=awards.jsonl ihalent-mcp
+```
+
+Pair it with ihale-mcp and an agent can collect notices and reason across them in one
+session: ihale-mcp fetches, ihalent structures and aggregates. The Python API
+(`ihalent.ingest_bundle`, `ihalent.analytics.firm_profile`) is three calls deep if you'd
+rather script it.
+
+## Scope, honestly
+
+- **This is analytics, not a scraper.** Collection is ihale-mcp's job (it does it well);
+  ihalent deliberately owns the layer above and stays a pure function of the data you give
+  it — no network, no signing keys, nothing that breaks when EKAP rotates a header.
+- **Company-name folding is conservative on purpose.** It merges legal-form suffixes and
+  Turkish spelling variants, and it would rather show two rows for one firm than one row for
+  two — so `firm` reports how many distinct spellings a query matched, and warns you if that
+  is more than one.
+- **The parser tracks one document: the result notice.** Bid-level detail (who else bid, at
+  what price) is not in the notice and so is not here. Discount is the estimate-to-contract
+  gap, which the notice does carry.
+- **Award values are nominal lira, as printed.** Comparing 2023 and 2026 contracts is your
+  analysis to make with the dates in hand; ihalent does not silently inflation-adjust.
+
+## What ihalent is not
+
+It is not a replacement for [ihale-mcp](https://github.com/saidsurucu/ihale-mcp) — it sits
+on top of it. It is not a live dashboard or a paid tender-alert service; it is a library and
+a CLI you point at data you control. And it does not redistribute a dataset: it ships the
+handful of real notices in `examples/` and the code to structure your own.
+
+## A note on the data
+
+Public-tender results are public information, published by the state for public scrutiny.
+ihalent structures what EKAP already discloses. Company names that appear are legal entities
+in their public commercial capacity, not private individuals.
+
+## How this project is built
+
+I designed the model and the analytics and I review every line; I use AI agents (Claude
+Code) heavily for implementation speed, and the commit trailers say so. The contract is the
+tests — 44 of them, built on the exact JSON shapes EKAP and ihale-mcp emit, including a
+result notice with a negative discount and a cancelled tender. They don't care who typed
+them.
+
+## License
+
+[MIT](LICENSE) — Mehmet Eren Gülmez

ihalent-0.1.0/docs/schema.md

@@ -0,0 +1,64 @@
+# Data model and JSON schema
+
+ihalent's interchange format is JSON Lines: one award per line. This page documents the
+`Award` record so you can produce it from any source, not only ihale-mcp.
+
+## Award
+
+| field | type | meaning |
+|---|---|---|
+| `ikn` | string | İhale Kayıt Numarası, e.g. `"2025/2198370"`. The primary key. |
+| `title` | string \| null | Tender title. |
+| `authority` | string \| null | Awarding authority (idare). |
+| `province` | string \| null | Province. |
+| `tender_type` | string | `mal` \| `yapim` \| `hizmet` \| `danismanlik` \| `unknown`. |
+| `estimate_try` | number \| null | Yaklaşık Maliyeti (public estimate), nominal lira. |
+| `contract_try` | number \| null | Sözleşme Bedeli (contract price), nominal lira. |
+| `winner` | string \| null | Lead bidder (first named party in a joint venture). |
+| `winners_all` | string[] | All named parties (the JV members). |
+| `is_joint_venture` | bool | True if the award went to an İş Ortaklığı. |
+| `downloaders` | int \| null | Firms that downloaded the documents. |
+| `bid_count` | int \| null | Toplam Teklif Sayısı. |
+| `valid_bid_count` | int \| null | Toplam Geçerli Teklif Sayısı. |
+| `result_date` | string \| null | Contract date, ISO (`YYYY-MM-DD`) where parseable. |
+| `cancelled` | bool | True for a cancelled tender (result notice with no winner/price). |
+
+Two fields are **computed** and appear in serialized output but are never stored as input:
+
+| field | type | meaning |
+|---|---|---|
+| `discount_pct` | number \| null | `100 * (estimate - contract) / estimate`, rounded to 2 dp. `null` if either value is missing or the estimate is 0. Negative means the contract came in *above* estimate. |
+| `single_bid` | bool \| null | `valid_bid_count <= 1`. `null` if the count is missing. |
+
+### The null discipline
+
+Every optional field is `null` when the source did not carry it — never `0`, never `""`.
+A discount computed from a missing estimate is `null`, not `0%`. This is load-bearing: the
+analytics layer counts these gaps and reports them (`data_gaps` in the overview, the
+`coverage` block on every statistic), so a mean is always qualified by how many records
+actually had the number.
+
+## Example line
+
+```json
+{"ikn": "2025/2198370", "title": "İSTANBUL ARNAVUTKÖY TÜRKKÖŞE DERESİ ISLAHI", "authority": "DSİ 14. Bölge Müdürlüğü", "province": "İstanbul", "tender_type": "yapim", "estimate_try": 29802943.48, "contract_try": 19709997.4, "winner": "ÖZDEN YEL", "winners_all": ["ÖZDEN YEL", "ATAŞ MÜHENDİSLİK ..."], "is_joint_venture": true, "downloaders": 34, "bid_count": 20, "valid_bid_count": 12, "result_date": "2026-02-13", "cancelled": false, "discount_pct": 33.87, "single_bid": false}
+```
+
+## Producing awards
+
+Three routes, all landing on the same JSONL:
+
+1. **From ihale-mcp / EKAP** — `ihalent ingest bundle.json` (or `ihalent.ingest_bundle` in
+   Python). Accepts a `get_tender_announcements` object, a list of them, or a list of
+   `{tender, announcements}` pairs.
+2. **From a single notice** — `ihalent parse notice.md` emits one record you can append.
+3. **From your own pipeline** — build `Award` objects directly and `dump_awards(...)`; only
+   `ikn` is required.
+
+## Company-name folding
+
+Firm queries and JV membership are matched on a normalized key: Turkish diacritics folded to
+ASCII, legal-form suffixes (`LİMİTED ŞİRKETİ`, `LTD ŞTİ`, `SANAYİ VE TİCARET ...`) stripped,
+whitespace and punctuation collapsed. The fold is deliberately conservative — it will not
+merge `ANADOLU İNŞAAT` with `ANKARA İNŞAAT` — and `firm` reports `distinct_spellings` so an
+over-broad query is visible rather than silently merging unrelated companies.

ihalent-0.1.0/examples/README.md

@@ -0,0 +1,25 @@
+# Example: four real December-2025 awards
+
+The `notices/` folder holds four real result notices (Sonuç İlanı), pulled from EKAP via
+ihale-mcp, one per file, named by İKN. They span four kinds of awarding authority on
+purpose:
+
+| İKN | authority | discount | note |
+|---|---|---|---|
+| 2025/2337797 | Ağrı İl Özel İdaresi | 19.99% | joint venture, provincial repair job |
+| 2025/2198370 | DSİ 14. Bölge Müdürlüğü | 33.87% | 12 valid bids — real competition |
+| 2025/2174700 | Esenler Belediyesi | 21.99% | municipal school/mosque repairs |
+| 2025/2388267 | İstanbul Üniversitesi-Cerrahpaşa | **-2.96%** | emergency "pazarlık", awarded *above* estimate |
+
+We ship the notices, not a redistributed dataset. `build_sample.py` parses them into
+`sample-awards.jsonl` exactly as `ihalent ingest` would with your own collected notices:
+
+```
+python build_sample.py
+ihalent overview   sample-awards.jsonl
+ihalent discounts  sample-awards.jsonl --by authority
+```
+
+The `-2.96%` case is the one to notice. A contract signed 2.96% above the public estimate,
+through an emergency procedure that skips open bidding, is exactly the kind of thing these
+notices disclose and nobody aggregates — which is the whole reason this tool exists.