Upload query stack release

README.md

@@ -0,0 +1,50 @@
+# Business Model KG Query Stack
+
+This model package contains the deployable local query stack for Business Model KG.
+
+It includes:
+
+- a DeBERTa-v3-small router classifier
+- calibrated router thresholds
+- an MLX QLoRA planner adapter for `mlx-community/Qwen3-4B-Instruct-2507-4bit`
+- the frozen planner system prompt
+- the runtime bundle manifest
+
+The package intentionally excludes optimizer states and intermediate training
+checkpoints. It is the deployable bundle, not the full training workspace.
+
+## Layout
+
+```text
+manifest.json
+router/
+  thresholds.json
+  model/
+planner/
+  system_prompt.txt
+  adapter/
+```
+
+## Base Models
+
+Router base model:
+
+```text
+microsoft/deberta-v3-small
+```
+
+Planner base model:
+
+```text
+mlx-community/Qwen3-4B-Instruct-2507-4bit
+```
+
+## Runtime Role
+
+The router chooses whether a user question is local-safe, should fall back to a
+hosted model, or should be refused. When the route is local, the planner emits a
+compact supported query plan that the Python runtime compiles into read-only
+Cypher.
+
+This bundle is meant to be consumed by the Business Model KG runtime as
+`runtime_assets/query_stack/current/`.

manifest.json

@@ -0,0 +1,16 @@
+{
+  "bundle_format_version": 1,
+  "published_at": "2026-04-25T09:13:47.641981+00:00",
+  "router": {
+    "base_model": "microsoft/deberta-v3-small",
+    "max_length": 256,
+    "model_dir": "router/model",
+    "thresholds_path": "router/thresholds.json"
+  },
+  "planner": {
+    "base_model": "mlx-community/Qwen3-4B-Instruct-2507-4bit",
+    "max_tokens": 256,
+    "adapter_dir": "planner/adapter",
+    "system_prompt_path": "planner/system_prompt.txt"
+  }
+}

planner/adapter/adapter_config.json

@@ -0,0 +1,35 @@
+{
+    "adapter_path": "/Users/giuliosighieri/Desktop/kg-v0/finetuning/artifacts/kg-query-planner-fresh-adapter/planner/adapter",
+    "batch_size": 4,
+    "data": "/Users/giuliosighieri/Desktop/kg-v0/finetuning/artifacts/kg-query-planner-fresh-adapter/prepared/planner/balanced",
+    "fine_tune_type": "lora",
+    "grad_accumulation_steps": 4,
+    "grad_checkpoint": true,
+    "iters": 7110,
+    "learning_rate": 0.0001,
+    "lora_parameters": {
+        "rank": 16,
+        "dropout": 0.05,
+        "scale": 32.0
+    },
+    "lr_schedule": null,
+    "mask_prompt": true,
+    "max_seq_length": 4096,
+    "model": "mlx-community/Qwen3-4B-Instruct-2507-4bit",
+    "num_layers": 16,
+    "optimizer": "adam",
+    "optimizer_config": {
+        "adam": {}
+    },
+    "project_name": null,
+    "report_to": null,
+    "resume_adapter_file": "/Users/giuliosighieri/Desktop/kg-v0/finetuning/artifacts/kg-query-planner-fresh-adapter/planner/adapter/checkpoints/0002000/adapters.safetensors",
+    "resume_checkpoint_dir": "/Users/giuliosighieri/Desktop/kg-v0/finetuning/artifacts/kg-query-planner-fresh-adapter/planner/adapter/checkpoints/0002000",
+    "save_every": 500,
+    "seed": 7,
+    "steps_per_eval": 2370,
+    "steps_per_report": 10,
+    "test": false,
+    "train": true,
+    "val_batches": -1
+}

planner/adapter/adapters.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d910f5e542f6e7b351d8141855504be94644ac5c86fa1f70bcdbb73f1e7c40a9
+size 58744712

planner/adapter/train_config.yaml

@@ -0,0 +1,23 @@
+model: 'mlx-community/Qwen3-4B-Instruct-2507-4bit'
+train: true
+test: false
+data: '/Users/giuliosighieri/Desktop/kg-v0/finetuning/artifacts/kg-query-planner-fresh-adapter/prepared/planner/balanced'
+seed: 7
+num_layers: 16
+batch_size: 4
+iters: 7110
+val_batches: -1
+learning_rate: 0.0001
+steps_per_report: 10
+steps_per_eval: 2370
+adapter_path: '/Users/giuliosighieri/Desktop/kg-v0/finetuning/artifacts/kg-query-planner-fresh-adapter/planner/adapter'
+save_every: 500
+max_seq_length: 4096
+grad_checkpoint: true
+grad_accumulation_steps: 4
+mask_prompt: true
+lora_parameters:
+  rank: 16
+  dropout: 0.05
+  scale: 32.0
+resume_checkpoint_dir: '/Users/giuliosighieri/Desktop/kg-v0/finetuning/artifacts/kg-query-planner-fresh-adapter/planner/adapter/checkpoints/0002000'

planner/system_prompt.txt

@@ -0,0 +1,75 @@
+You translate natural-language questions into compact JSON plans for the production business-model knowledge graph. Do not write Cypher. The runtime compiles your plan into Cypher deterministically.
+
+OUTPUT CONTRACT
+- For supported requests return {"answerable": true, "family": "...", "payload": {...}}.
+- For unsupported, ambiguous, or out-of-coverage requests return {"answerable": false, "reason": "..."}
+- Valid refusal reasons are unsupported_schema, unsupported_metric, unsupported_time, ambiguous_closed_label, ambiguous_request, write_request, and beyond_local_coverage.
+- Output compact JSON only. No markdown, no prose, no explanation, no chain-of-thought.
+
+DATABASE ARCHITECTURE
+- Node labels: Company, BusinessSegment, Offering, CustomerType, Channel, RevenueModel, and Place.
+- Relationship types: HAS_SEGMENT, OFFERS, SERVES, SELLS_THROUGH, MONETIZES_VIA, OPERATES_IN, and PARTNERS_WITH.
+- Company nodes are keyed by name.
+- BusinessSegment and Offering are company-scoped in downstream querying.
+- SERVES and SELLS_THROUGH live on BusinessSegment in the local-safe query families.
+- MONETIZES_VIA lives only on Offering.
+- OPERATES_IN and PARTNERS_WITH live only on Company.
+- Offering families use Offering-[:OFFERS]->Offering recursively.
+- Place nodes may carry within_places and includes_places arrays for geographic rollups.
+
+CLOSED LABELS
+- CustomerType is a closed vocabulary. Valid labels are consumers, small businesses, mid-market companies, large enterprises, developers, IT professionals, government agencies, educational institutions, healthcare organizations, financial services firms, manufacturers, and retailers.
+- Channel is a closed vocabulary. Valid labels are direct sales, online, retail, distributors, resellers, OEMs, system integrators, managed service providers, and marketplaces.
+- RevenueModel is a closed vocabulary. Valid labels are subscription, advertising, licensing, consumption-based, hardware sales, service fees, royalties, and transaction fees.
+- Always normalize user wording to the exact canonical closed label before returning payload values.
+- Examples: government, public sector, or agencies -> government agencies.
+- Examples: healthcare firms, hospitals, providers, or health systems -> healthcare organizations.
+- Examples: enterprise customers -> large enterprises when that is the closest canonical label.
+- If the wording does not map clearly to one canonical closed label, refuse with ambiguous_closed_label.
+
+OPEN LITERAL COPYING
+- companies, partners, segments, offerings, and places are open-class literals, not closed vocabularies.
+- Copy open-class literals exactly as written in the user request unless an exact canonical place synonym is already established elsewhere in the prompt.
+- Never paraphrase, respell, split, merge, autocorrect, or partially normalize company, partner, segment, or offering names.
+- Do not invent punctuation or whitespace inside copied literals.
+- Examples: Nimbus Health -> companies:["Nimbus Health"]; MediSupply -> partners:["MediSupply"]; Vector Industrial -> companies:["Vector Industrial"].
+- Only normalize closed vocabularies such as customer_types, channels, and revenue_models.
+
+QUERY FAMILY CATALOG
+- companies_list
+- segments_by_company
+- offerings_by_company
+- offerings_by_segment
+- companies_by_segment_filters
+- segments_by_segment_filters
+- companies_by_cross_segment_filters
+- descendant_offerings_by_root
+- companies_by_descendant_revenue
+- companies_by_place
+- segments_by_place_and_segment_filters
+- companies_by_partner
+- boolean_exists
+- count_aggregate
+- ranking_topk
+
+PAYLOAD FIELDS
+- Use only these payload keys when they are needed: companies, segments, offerings, customer_types, channels, revenue_models, places, partners, binding_scope, hierarchy_mode, aggregate_spec, base_family, and limit.
+- companies, segments, offerings, places, and partners are list-valued union filters by default.
+- Repeated customer_types, channels, offerings, and revenue_models inside segment-filter families are cumulative constraints, not free-form prose.
+- binding_scope is same_segment or across_segments.
+- hierarchy_mode is direct or descendant.
+- boolean_exists uses base_family plus the same filter payload as the referenced lookup family.
+- count_aggregate uses aggregate_spec.kind=count, aggregate_spec.base_family, and aggregate_spec.count_target.
+- ranking_topk uses aggregate_spec.kind=ranking and one whitelisted ranking metric.
+
+SUPPORTED AGGREGATES
+- Count targets: company, segment, and offering.
+- Whitelisted ranking metrics are customer_type_by_company_count, channel_by_segment_count, revenue_model_by_company_count, and company_by_matched_segment_count.
+- Use limit for top-k style requests.
+
+REFUSE IN THESE CASES
+- Temporal questions, trends, dates, or year-over-year requests -> unsupported_time.
+- Unsupported metrics such as revenue amounts, prices, growth, employees, or suppliers -> unsupported_metric or unsupported_schema.
+- Write or mutate requests -> write_request.
+- Free-form explanations, why-questions, and unsupported set comparisons -> beyond_local_coverage.
+- Ambiguous requests that do not map safely to one family and payload -> ambiguous_request.

router/model/added_tokens.json

@@ -0,0 +1,3 @@
+{
+  "[MASK]": 128000
+}

router/model/config.json

@@ -0,0 +1,47 @@
+{
+  "architectures": [
+    "DebertaV2ForSequenceClassification"
+  ],
+  "attention_probs_dropout_prob": 0.1,
+  "bos_token_id": 1,
+  "dtype": "float32",
+  "eos_token_id": 2,
+  "hidden_act": "gelu",
+  "hidden_dropout_prob": 0.1,
+  "hidden_size": 768,
+  "id2label": {
+    "0": "api_fallback",
+    "1": "local",
+    "2": "refuse"
+  },
+  "initializer_range": 0.02,
+  "intermediate_size": 3072,
+  "label2id": {
+    "api_fallback": 0,
+    "local": 1,
+    "refuse": 2
+  },
+  "layer_norm_eps": 1e-07,
+  "legacy": true,
+  "max_position_embeddings": 512,
+  "max_relative_positions": -1,
+  "model_type": "deberta-v2",
+  "norm_rel_ebd": "layer_norm",
+  "num_attention_heads": 12,
+  "num_hidden_layers": 6,
+  "pad_token_id": 0,
+  "pooler_dropout": 0,
+  "pooler_hidden_act": "gelu",
+  "pooler_hidden_size": 768,
+  "pos_att_type": [
+    "p2c",
+    "c2p"
+  ],
+  "position_biased_input": false,
+  "position_buckets": 256,
+  "relative_attention": true,
+  "share_att_key": true,
+  "transformers_version": "4.57.6",
+  "type_vocab_size": 0,
+  "vocab_size": 128100
+}

router/model/model.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:6ef0e8d3c5c9ebe4723f66544dfd1b45d49a4e0d435708056d94e99b09fafd9f
+size 567601628

router/model/special_tokens_map.json

@@ -0,0 +1,15 @@
+{
+  "bos_token": "[CLS]",
+  "cls_token": "[CLS]",
+  "eos_token": "[SEP]",
+  "mask_token": "[MASK]",
+  "pad_token": "[PAD]",
+  "sep_token": "[SEP]",
+  "unk_token": {
+    "content": "[UNK]",
+    "lstrip": false,
+    "normalized": true,
+    "rstrip": false,
+    "single_word": false
+  }
+}

router/model/spm.model

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:c679fbf93643d19aab7ee10c0b99e460bdbc02fedf34b92b05af343b4af586fd
+size 2464616

router/model/tokenizer_config.json

@@ -0,0 +1,59 @@
+{
+  "added_tokens_decoder": {
+    "0": {
+      "content": "[PAD]",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "1": {
+      "content": "[CLS]",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "2": {
+      "content": "[SEP]",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "3": {
+      "content": "[UNK]",
+      "lstrip": false,
+      "normalized": true,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "128000": {
+      "content": "[MASK]",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    }
+  },
+  "bos_token": "[CLS]",
+  "clean_up_tokenization_spaces": false,
+  "cls_token": "[CLS]",
+  "do_lower_case": false,
+  "eos_token": "[SEP]",
+  "extra_special_tokens": {},
+  "mask_token": "[MASK]",
+  "model_max_length": 1000000000000000019884624838656,
+  "pad_token": "[PAD]",
+  "sep_token": "[SEP]",
+  "sp_model_kwargs": {},
+  "split_by_punct": false,
+  "tokenizer_class": "DebertaV2Tokenizer",
+  "unk_token": "[UNK]",
+  "vocab_type": "spm"
+}

router/model/training_args.bin

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:65d4e26fe0faa624bcecbbbe5f82997efbf2bda39abfbde6863411e79da6e325
+size 5969

router/model/training_summary.json

@@ -0,0 +1,18 @@
+{
+  "output_dir": "/Users/giuliosighieri/Desktop/kg-v0/finetuning/artifacts/kg-query-planner/router/model",
+  "train_examples": 8000,
+  "valid_examples": 1200,
+  "label_counts": {
+    "api_fallback": 1500,
+    "local": 5000,
+    "refuse": 1500
+  },
+  "train_metrics": {
+    "train_runtime": 157.9059,
+    "train_samples_per_second": 303.978,
+    "train_steps_per_second": 18.999,
+    "total_flos": 202218153306336.0,
+    "train_loss": 0.05477014222391881,
+    "epoch": 3.0
+  }
+}

router/thresholds.json

@@ -0,0 +1,16 @@
+{
+  "temperature": 0.9993856549263,
+  "local_threshold": {
+    "threshold": 5.6824406783562154e-05,
+    "precision": 0.9702457956015524,
+    "recall": 1.0,
+    "support": 773
+  },
+  "refuse_threshold": {
+    "threshold": 8.565641473978758e-05,
+    "precision": 0.9527896995708155,
+    "recall": 1.0,
+    "support": 233
+  },
+  "planner_gate_open": true
+}