Initial release (approved by Luca, 2026-10-06)

LICENSE.md

@@ -0,0 +1,36 @@
+# JOA Model License, version 1.0 (PLANNED)
+
+**Status: planned. This licence applies only once Job Opportunities API releases model weights. No weights are released yet.**
+
+Licensor: Loukas Tzekos, trading as Job Opportunities API (JOA), sole proprietorship, Didaskalisis Papathanasiou Vas. 79, 54629 Thessaloniki, Greece, VAT EL117613696. Legal matters: luca@tzekos.eu.
+
+"The Model" means the weights and adapters of JOA Small (and of JOA Small, JOA Advance and JOA Deep generally) as released by the Licensor, and any files released with them. "Derivative" means any model or adapter made from the Model, for example by fine-tuning, merging, quantising or distillation.
+
+## 1. What you may do
+
+You may use, copy, modify, fine-tune, merge, quantise, distribute and sell the Model and Derivatives, and use them in any product or service, including commercial and hosted services. The licence is free of charge, worldwide, non-exclusive and lasts as long as the rights it covers.
+
+## 2. Conditions
+
+These conditions apply when you distribute the Model or a Derivative, or make a product or service that uses them available to anyone outside your own organisation (including through an app, website or hosted API). Purely internal use has no conditions beyond sections 2.4 and 3.
+
+1. **Keep the base model's licence.** The Model is built on a base model licensed under the Apache License, Version 2.0. Include that licence and any copyright and NOTICE text of the base model, and state that the weights were modified. Nothing in this licence limits the rights you have in the base model itself, obtained from its publisher, under its own licence.
+2. **Give visible credit.** Display the line "Built with JOA Small by Job Opportunities API" with a link to https://jobopportunitiesapi.org, where users of your product or service can see it: in its documentation, its about page or its user interface. If you publish a Derivative, put the same line and link in its model card or README.
+3. **Pass this licence on.** Include a copy of this licence with every copy of the Model or a Derivative you distribute. You may license your own changes on your own terms, but these conditions continue to apply to the parts that come from the Model.
+4. **No implied endorsement.** You may say that your work is based on JOA Small. Do not name or present it in a way that suggests Job Opportunities API, IBM, Alibaba Cloud or the Qwen team made, endorse or support it. This licence grants no trademark rights.
+
+## 3. Outputs
+
+What you generate with the Model is yours. This licence puts no conditions on outputs.
+
+## 4. Ending and restoring the licence
+
+If you break a condition, your rights under this licence end automatically. They come back if you fix the breach within 30 days of becoming aware of it.
+
+## 5. No warranty
+
+The Model is provided "as is", without warranty of any kind. To the extent permitted by law, the Licensor is not liable for any damage arising from its use.
+
+## 6. Law
+
+This licence is governed by Greek law. This does not remove any rights consumers have under the law of their own country.

README.md

@@ -0,0 +1,79 @@
+---
+license: other
+license_name: joa-model-license
+license_link: LICENSE.md
+base_model: ibm-granite/granite-4.2-3b
+base_model_relation: adapter
+pipeline_tag: text-generation
+tags:
+- information-extraction
+- job-postings
+- lora
+---
+
+# JOA Small: job-posting extraction model (status page, weights not released)
+
+*Disclosure: Job Opportunities API (JOA, jobopportunitiesapi.org) is an independent data business that sells API access to job-posting data. AI helped run the experiments, check the numbers and draft this text; Loukas (Luca) Tzekos is editorially responsible. Contact: hello@jobopportunitiesapi.org.*
+
+**Status (6 October 2026): trained and evaluated, weights not published.** This page records what the model does and how it scored. It will be updated if and when weights are released. Planned licence for the weights: the JOA Model License (any use, including commercial, with visible credit and a link); it applies only once weights are released.
+
+## What it does
+
+JOA Small reads the text of one job posting and returns 11 structured fields as JSON: title, company, location, salary currency, minimum, maximum and period, seniority, remote type, posted date, and whether the poster is a staffing agency. It leaves a field empty when the posting does not state it. It answers directly, without a long reasoning trace.
+
+## How it was made
+
+- **Base model:** [ibm-granite/granite-4.2-3b](https://huggingface.co/ibm-granite/granite-4.2-3b) by IBM, licensed Apache 2.0.
+- **Method:** LoRA adapter (rank 16), one epoch, 80,000 training examples.
+- **Training data:** fields extracted by Qwen/Qwen3.5-27B (Apache 2.0) from job postings collected by Job Opportunities API (JOA), kept only when grounded in the posting text (for example, a title or salary that actually appears in it). The 250 arena listings and the 250 verification listings were excluded.
+- **Compute:** This work used the EuroHPC supercomputer Discoverer+ in Bulgaria, made available by the EuroHPC Joint Undertaking through an AI Factories Playground access allocation (project EHPC-AIF-2026PG01-1124).
+
+## Results
+
+**Extraction arena** (250 real job listings, 11 fields, two judge models, paired bootstrap; graded 2 October 2026). Dataset: https://huggingface.co/datasets/JobOpportunitiesAPI/joa-extraction-arena
+
+| Model | Score (rule A) | 95% range | Rank of 84 | Median output tokens |
+|---|---|---|---|---|
+| **JOA Small** | **93.3** | 92.2–94.4 | **1** | 117 |
+| Stock granite-4.2-3b | 64.5 | 59.7–69.0 | 71 | 4,411 |
+| Trainer Qwen/Qwen3.5-27B | 89.2 | 86.9–91.4 | 4 | 2,946 |
+
+Per field (rule A): title 99, company 96, location 89, salary currency 93, salary min 94, salary max 93, salary period 96, seniority 86, remote type 92, posted date 89, agency 96.
+
+**Verified listings** (a second set of 250 recent listings, each verified twice by Claude Opus against the live page and the application flow; exact match on the open listings that all three models answered; scored 2 October 2026): stock granite-4.2-3b 72.3%, **JOA Small 84.9%**, trainer 86.3% (n = 213).
+
+**Consumer graphics card** (4–5 October 2026, 100 different JOA listings, richer input with the page and structured data, graded against Claude Opus references): F1 0.888 (95% range 0.85–0.92), about 7 seconds per listing on an NVIDIA GTX 1070.
+
+## Known limits
+
+- **It reads JOA's stored text, not the live page.** That text is usually the description body; the page header, where the title, location and posted date often sit, can be missing. A field that is not in the input cannot be extracted.
+- **It cannot tell that a job has closed.** On the verification set it called a few dead listings open; the stored text carries no sign of closure. JOA checks liveness separately.
+- **It cannot drive a tool-using agent.** Given tools instead of a prepared input, it scored F1 0.520 on the same 100 listings, and only 54 of 100 answers could be parsed. Give it the input; do not ask it to fetch it.
+- **The reference answers come from a model, and the judges are models.** Two judges, a checked reference and confidence ranges reduce that risk; they do not remove it.
+- **One task.** This is an extraction model for job postings, not a general assistant.
+
+## What is next
+
+Train and test on a richer input (the rendered page, structured data and the recruiting system's own data), re-run both tests, then decide on releasing the weights.
+
+## Licence (planned)
+
+When the weights are released, they will be licensed under the **JOA Model License** (LICENSE.md in this repository):
+
+- You may use, modify, fine-tune, redistribute and sell JOA Small, including in commercial and hosted products.
+- If you distribute it, or make a product or service that uses it available to others, show "Built with JOA Small by Job Opportunities API" with a link to https://jobopportunitiesapi.org in your documentation, about page or user interface, and in the model card of any derivative.
+- Keep the base model's Apache 2.0 licence and notices.
+- Do not imply endorsement.
+
+Nothing is released yet. This section describes the plan, not a grant.
+
+## Attribution
+
+JOA Small is a fine-tune of ibm-granite/granite-4.2-3b by IBM, used under the Apache License 2.0. It is not made, endorsed or supported by IBM. Built by Job Opportunities API (JOA), https://jobopportunitiesapi.org.
+
+## Contact
+
+- General: hello@jobopportunitiesapi.org
+- Legal matters: luca@tzekos.eu
+- Phone: +30 2311 113 603
+- Job Opportunities API (JOA) is a sole proprietorship of Loukas Tzekos, Didaskalisis Papathanasiou Vas. 79, 54629 Thessaloniki, Greece. VAT EL117613696.