updated the README

README.md

@@ -1,378 +1,176 @@
----
-tags:
-- sentence-transformers
-- sentence-similarity
-- feature-extraction
-- dense
-- generated_from_trainer
-- dataset_size:309
-- loss:MultipleNegativesRankingLoss
-base_model: sentence-transformers/all-MiniLM-L6-v2
-widget:
-- source_sentence: Find the element that handles identifies the underlying asset when
-    it is an exchange-traded fund.
-  sentences:
-  - '[exchangeTradedFund]: Identifies the underlying asset when it is an exchange-traded
-    fund.'
-  - '[mutualFund]: Identifies the class of unit issued by a fund.'
-  - '[lcIssuanceFeePayment]: No description available'
-- source_sentence: Find the element that handles specifies the return payments of
-    a commodity return swap.
-  sentences:
-  - '[consentRefused]: No description available'
-  - '[commodityReturnLeg]: Specifies the return payments of a commodity return swap.
-    There can be one or two return legs. In simple return swaps there is a return
-    leg and an interest (a.k.a. ''fee'') leg. In the case of a outperformance swap
-    there are two return legs: the return performance of two commodity underlyers
-    are swapped. In the case of a fully-funded return swap there is no financing component
-    and, therefore, only a single return leg is specified.'
-  - '[loanTrade]: No description available'
-- source_sentence: The fpml tag for the parameters for defining the exercise period
-    for a european style option together with any rules governing the notional amount
-    of the underlying which can be exercised on any given exercise date and any associated
-    exercise fees.
-  sentences:
-  - '[priceSourceDisruption]: If present indicates that the event is considered to
-    have occurred if it is impossible to obtain information about the Spot Rate for
-    a Valuation Date from the price source specified in the Settlement Rate Option
-    that hass been agreed by the parties.'
-  - '[europeanExercise]: The parameters for defining the exercise period for a European
-    style option together with any rules governing the notional amount of the underlying
-    which can be exercised on any given exercise date and any associated exercise
-    fees.'
-  - '[nonDeliverableSubstitute]: If present indicates that the obligation to pay the
-    In-the-Money amount of foreign currency is replaced with an obligation to pay
-    an equivalent amount in another currency.'
-- source_sentence: The fpml tag for global element representing a repo.
-  sentences:
-  - '[facilityPrepaymentFeePayment]: No description available'
-  - '[product]: An abstract element used as a place holder for the substituting product
-    elements.'
-  - '[repo]: Global element representing a Repo.'
-- source_sentence: Can you give me the fpml tag for fxcurvevaluation?
-  sentences:
-  - '[fxCurveValuation]: No description available'
-  - '[loanLegalActionStatement]: No description available'
-  - '[loanAllocationSettlementDateAvailability]: No description available'
-pipeline_tag: sentence-similarity
-library_name: sentence-transformers
----
-
-# SentenceTransformer based on sentence-transformers/all-MiniLM-L6-v2
-
-This is a [sentence-transformers](https://www.SBERT.net) model finetuned from [sentence-transformers/all-MiniLM-L6-v2](https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2). It maps sentences & paragraphs to a 384-dimensional dense vector space and can be used for semantic textual similarity, semantic search, paraphrase mining, text classification, clustering, and more.
-
-## Model Details
-
-### Model Description
-- **Model Type:** Sentence Transformer
-- **Base model:** [sentence-transformers/all-MiniLM-L6-v2](https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2) <!-- at revision c9745ed1d9f207416be6d2e6f8de32d1f16199bf -->
-- **Maximum Sequence Length:** 256 tokens
-- **Output Dimensionality:** 384 dimensions
-- **Similarity Function:** Cosine Similarity
-<!-- - **Training Dataset:** Unknown -->
-<!-- - **Language:** Unknown -->
-<!-- - **License:** Unknown -->
-
-### Model Sources
-
-- **Documentation:** [Sentence Transformers Documentation](https://sbert.net)
-- **Repository:** [Sentence Transformers on GitHub](https://github.com/huggingface/sentence-transformers)
-- **Hugging Face:** [Sentence Transformers on Hugging Face](https://huggingface.co/models?library=sentence-transformers)
-
-### Full Model Architecture
-
-```
-SentenceTransformer(
-  (0): Transformer({'max_seq_length': 256, 'do_lower_case': False, 'architecture': 'BertModel'})
-  (1): Pooling({'word_embedding_dimension': 384, 'pooling_mode_cls_token': False, 'pooling_mode_mean_tokens': True, 'pooling_mode_max_tokens': False, 'pooling_mode_mean_sqrt_len_tokens': False, 'pooling_mode_weightedmean_tokens': False, 'pooling_mode_lasttoken': False, 'include_prompt': True})
-  (2): Normalize()
-)
-```
-
-## Usage
-
-### Direct Usage (Sentence Transformers)
-
-First install the Sentence Transformers library:
-
-```bash
-pip install -U sentence-transformers
-```
-
-Then you can load this model and run inference.
-```python
-from sentence_transformers import SentenceTransformer
-
-# Download from the 🤗 Hub
-model = SentenceTransformer("thelocalhost/fpml-semantic-model")
-# Run inference
-sentences = [
-    'Can you give me the fpml tag for fxcurvevaluation?',
-    '[fxCurveValuation]: No description available',
-    '[loanLegalActionStatement]: No description available',
-]
-embeddings = model.encode(sentences)
-print(embeddings.shape)
-# [3, 384]
-
-# Get the similarity scores for the embeddings
-similarities = model.similarity(embeddings, embeddings)
-print(similarities)
-# tensor([[1.0000, 0.6213, 0.2119],
-#         [0.6213, 1.0000, 0.5905],
-#         [0.2119, 0.5905, 1.0000]])
-```
-
-<!--
-### Direct Usage (Transformers)
-
-<details><summary>Click to see the direct usage in Transformers</summary>
-
-</details>
--->
-
-<!--
-### Downstream Usage (Sentence Transformers)
-
-You can finetune this model on your own dataset.
-
-<details><summary>Click to expand</summary>
-
-</details>
--->
-
-<!--
-### Out-of-Scope Use
-
-*List how the model may foreseeably be misused and address what users ought not to do with the model.*
--->
-
-<!--
-## Bias, Risks and Limitations
-
-*What are the known or foreseeable issues stemming from this model? You could also flag here known failure cases or weaknesses of the model.*
--->
-
-<!--
-### Recommendations
-
-*What are recommendations with respect to the foreseeable issues? For example, filtering explicit content.*
--->
-
-## Training Details
-
-### Training Dataset
-
-#### Unnamed Dataset
-
-* Size: 309 training samples
-* Columns: <code>sentence_0</code> and <code>sentence_1</code>
-* Approximate statistics based on the first 309 samples:
-  |         | sentence_0                                                                        | sentence_1                                                                         |
-  |:--------|:----------------------------------------------------------------------------------|:-----------------------------------------------------------------------------------|
-  | type    | string                                                                            | string                                                                             |
-  | details | <ul><li>min: 9 tokens</li><li>mean: 16.67 tokens</li><li>max: 58 tokens</li></ul> | <ul><li>min: 9 tokens</li><li>mean: 20.44 tokens</li><li>max: 177 tokens</li></ul> |
-* Samples:
-  | sentence_0                                                                                          | sentence_1                                                                                                                                                                                                                                                                                        |
-  |:----------------------------------------------------------------------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-  | <code>Can you give me the fpml tag for loanpartyprofilestatement?</code>                            | <code>[loanPartyProfileStatement]: No description available</code>                                                                                                                                                                                                                                |
-  | <code>What is the structure of valuationpostponement?</code>                                        | <code>[valuationPostponement]: Indicates that the Valuation Date for the tranaction shall be deemed to be the first Business Day following the day on which the applicable Disruption Event ceases to exist, unless the events continues to exists for more than a maximum number of days.</code> |
-  | <code>I need the fpml tag related to allocationacknowledgement and no description available.</code> | <code>[allocationAcknowledgement]: No description available</code>                                                                                                                                                                                                                                |
-* Loss: [<code>MultipleNegativesRankingLoss</code>](https://sbert.net/docs/package_reference/sentence_transformer/losses.html#multiplenegativesrankingloss) with these parameters:
-  ```json
-  {
-      "scale": 20.0,
-      "similarity_fct": "cos_sim",
-      "gather_across_devices": false
-  }
-  ```
-
-### Training Hyperparameters
-#### Non-Default Hyperparameters
-
-- `per_device_train_batch_size`: 16
-- `per_device_eval_batch_size`: 16
-- `fp16`: True
-- `multi_dataset_batch_sampler`: round_robin
-
-#### All Hyperparameters
-<details><summary>Click to expand</summary>
-
-- `overwrite_output_dir`: False
-- `do_predict`: False
-- `eval_strategy`: no
-- `prediction_loss_only`: True
-- `per_device_train_batch_size`: 16
-- `per_device_eval_batch_size`: 16
-- `per_gpu_train_batch_size`: None
-- `per_gpu_eval_batch_size`: None
-- `gradient_accumulation_steps`: 1
-- `eval_accumulation_steps`: None
-- `torch_empty_cache_steps`: None
-- `learning_rate`: 5e-05
-- `weight_decay`: 0.0
-- `adam_beta1`: 0.9
-- `adam_beta2`: 0.999
-- `adam_epsilon`: 1e-08
-- `max_grad_norm`: 1
-- `num_train_epochs`: 3
-- `max_steps`: -1
-- `lr_scheduler_type`: linear
-- `lr_scheduler_kwargs`: {}
-- `warmup_ratio`: 0.0
-- `warmup_steps`: 0
-- `log_level`: passive
-- `log_level_replica`: warning
-- `log_on_each_node`: True
-- `logging_nan_inf_filter`: True
-- `save_safetensors`: True
-- `save_on_each_node`: False
-- `save_only_model`: False
-- `restore_callback_states_from_checkpoint`: False
-- `no_cuda`: False
-- `use_cpu`: False
-- `use_mps_device`: False
-- `seed`: 42
-- `data_seed`: None
-- `jit_mode_eval`: False
-- `bf16`: False
-- `fp16`: True
-- `fp16_opt_level`: O1
-- `half_precision_backend`: auto
-- `bf16_full_eval`: False
-- `fp16_full_eval`: False
-- `tf32`: None
-- `local_rank`: 0
-- `ddp_backend`: None
-- `tpu_num_cores`: None
-- `tpu_metrics_debug`: False
-- `debug`: []
-- `dataloader_drop_last`: False
-- `dataloader_num_workers`: 0
-- `dataloader_prefetch_factor`: None
-- `past_index`: -1
-- `disable_tqdm`: False
-- `remove_unused_columns`: True
-- `label_names`: None
-- `load_best_model_at_end`: False
-- `ignore_data_skip`: False
-- `fsdp`: []
-- `fsdp_min_num_params`: 0
-- `fsdp_config`: {'min_num_params': 0, 'xla': False, 'xla_fsdp_v2': False, 'xla_fsdp_grad_ckpt': False}
-- `fsdp_transformer_layer_cls_to_wrap`: None
-- `accelerator_config`: {'split_batches': False, 'dispatch_batches': None, 'even_batches': True, 'use_seedable_sampler': True, 'non_blocking': False, 'gradient_accumulation_kwargs': None}
-- `parallelism_config`: None
-- `deepspeed`: None
-- `label_smoothing_factor`: 0.0
-- `optim`: adamw_torch_fused
-- `optim_args`: None
-- `adafactor`: False
-- `group_by_length`: False
-- `length_column_name`: length
-- `project`: huggingface
-- `trackio_space_id`: trackio
-- `ddp_find_unused_parameters`: None
-- `ddp_bucket_cap_mb`: None
-- `ddp_broadcast_buffers`: False
-- `dataloader_pin_memory`: True
-- `dataloader_persistent_workers`: False
-- `skip_memory_metrics`: True
-- `use_legacy_prediction_loop`: False
-- `push_to_hub`: False
-- `resume_from_checkpoint`: None
-- `hub_model_id`: None
-- `hub_strategy`: every_save
-- `hub_private_repo`: None
-- `hub_always_push`: False
-- `hub_revision`: None
-- `gradient_checkpointing`: False
-- `gradient_checkpointing_kwargs`: None
-- `include_inputs_for_metrics`: False
-- `include_for_metrics`: []
-- `eval_do_concat_batches`: True
-- `fp16_backend`: auto
-- `push_to_hub_model_id`: None
-- `push_to_hub_organization`: None
-- `mp_parameters`: 
-- `auto_find_batch_size`: False
-- `full_determinism`: False
-- `torchdynamo`: None
-- `ray_scope`: last
-- `ddp_timeout`: 1800
-- `torch_compile`: False
-- `torch_compile_backend`: None
-- `torch_compile_mode`: None
-- `include_tokens_per_second`: False
-- `include_num_input_tokens_seen`: no
-- `neftune_noise_alpha`: None
-- `optim_target_modules`: None
-- `batch_eval_metrics`: False
-- `eval_on_start`: False
-- `use_liger_kernel`: False
-- `liger_kernel_config`: None
-- `eval_use_gather_object`: False
-- `average_tokens_across_devices`: True
-- `prompts`: None
-- `batch_sampler`: batch_sampler
-- `multi_dataset_batch_sampler`: round_robin
-- `router_mapping`: {}
-- `learning_rate_mapping`: {}
-
-</details>
-
-### Framework Versions
-- Python: 3.13.5
-- Sentence Transformers: 5.1.2
-- Transformers: 4.57.1
-- PyTorch: 2.9.0+cpu
-- Accelerate: 1.11.0
-- Datasets: 4.4.1
-- Tokenizers: 0.22.1
-
-## Citation
-
-### BibTeX
-
-#### Sentence Transformers
-```bibtex
-@inproceedings{reimers-2019-sentence-bert,
-    title = "Sentence-BERT: Sentence Embeddings using Siamese BERT-Networks",
-    author = "Reimers, Nils and Gurevych, Iryna",
-    booktitle = "Proceedings of the 2019 Conference on Empirical Methods in Natural Language Processing",
-    month = "11",
-    year = "2019",
-    publisher = "Association for Computational Linguistics",
-    url = "https://arxiv.org/abs/1908.10084",
-}
-```
-
-#### MultipleNegativesRankingLoss
-```bibtex
-@misc{henderson2017efficient,
-    title={Efficient Natural Language Response Suggestion for Smart Reply},
-    author={Matthew Henderson and Rami Al-Rfou and Brian Strope and Yun-hsuan Sung and Laszlo Lukacs and Ruiqi Guo and Sanjiv Kumar and Balint Miklos and Ray Kurzweil},
-    year={2017},
-    eprint={1705.00652},
-    archivePrefix={arXiv},
-    primaryClass={cs.CL}
-}
-```
-
-<!--
-## Glossary
-
-*Clearly define terms in order to be accessible across audiences.*
--->
-
-<!--
-## Model Card Authors
-
-*Lists the people who create the model card, providing recognition and accountability for the detailed work that goes into its construction.*
--->
-
-<!--
-## Model Card Contact
-
-*Provides a way for people who have updates to the Model Card, suggestions, or questions, to contact the Model Card authors.*
--->
+---
+tags:
+- sentence-transformers
+- sentence-similarity
+- feature-extraction
+- dense
+- generated_from_trainer
+- dataset_size:309
+- loss:MultipleNegativesRankingLoss
+base_model: sentence-transformers/all-MiniLM-L6-v2
+widget:
+- source_sentence: Find the element that handles identifies the underlying asset when
+    it is an exchange-traded fund.
+  sentences:
+  - '[exchangeTradedFund]: Identifies the underlying asset when it is an exchange-traded
+    fund.'
+  - '[mutualFund]: Identifies the class of unit issued by a fund.'
+  - '[lcIssuanceFeePayment]: No description available'
+- source_sentence: Find the element that handles specifies the return payments of
+    a commodity return swap.
+  sentences:
+  - '[consentRefused]: No description available'
+  - '[commodityReturnLeg]: Specifies the return payments of a commodity return swap.
+    There can be one or two return legs. In simple return swaps there is a return
+    leg and an interest (a.k.a. ''fee'') leg. In the case of a outperformance swap
+    there are two return legs: the return performance of two commodity underlyers
+    are swapped. In the case of a fully-funded return swap there is no financing component
+    and, therefore, only a single return leg is specified.'
+  - '[loanTrade]: No description available'
+- source_sentence: The fpml tag for the parameters for defining the exercise period
+    for a european style option together with any rules governing the notional amount
+    of the underlying which can be exercised on any given exercise date and any associated
+    exercise fees.
+  sentences:
+  - '[priceSourceDisruption]: If present indicates that the event is considered to
+    have occurred if it is impossible to obtain information about the Spot Rate for
+    a Valuation Date from the price source specified in the Settlement Rate Option
+    that hass been agreed by the parties.'
+  - '[europeanExercise]: The parameters for defining the exercise period for a European
+    style option together with any rules governing the notional amount of the underlying
+    which can be exercised on any given exercise date and any associated exercise
+    fees.'
+  - '[nonDeliverableSubstitute]: If present indicates that the obligation to pay the
+    In-the-Money amount of foreign currency is replaced with an obligation to pay
+    an equivalent amount in another currency.'
+- source_sentence: The fpml tag for global element representing a repo.
+  sentences:
+  - '[facilityPrepaymentFeePayment]: No description available'
+  - '[product]: An abstract element used as a place holder for the substituting product
+    elements.'
+  - '[repo]: Global element representing a Repo.'
+- source_sentence: Can you give me the fpml tag for fxcurvevaluation?
+  sentences:
+  - '[fxCurveValuation]: No description available'
+  - '[loanLegalActionStatement]: No description available'
+  - '[loanAllocationSettlementDateAvailability]: No description available'
+pipeline_tag: sentence-similarity
+library_name: sentence-transformers
+---
+
+
+# thelocalhost/fpml-semantic-model
+
+This is the fpml-semantic-model version of the sentence-transformers/all-MiniLM-L6-v2 for generating text embeddings.
+
+## Specialized Semantic Search Model for FpML XSD
+
+This model, fpml-semantic-model, is a specialized version of the base all-MiniLM-L6-v2 Sentence Transformer, fine-tuned on proprietary data derived from FpML XSD schema definitions and documentation. It is engineered to provide superior semantic relevance for financial terminology, significantly outperforming general-purpose models when searching FpML data structures.
+
+The `fpml-semantic-model` provides a robust, offline-capable utility for performing **semantic searches** across the Financial products Markup Language (FpML) XSD schema definitions. Instead of relying on exact keyword matches, this model allows users to search for complex FpML elements using natural language, helping developers and analysts quickly locate the correct XML structure for derivatives and financial transaction data.
+
+## 💡 Model Overview
+
+This model maps complex natural language queries about financial concepts directly to the specific FpML tags and definitions within the schema.
+
+### Key Use Cases
+
+- Schema Exploration: Quickly locate the exact FpML element (e.g., tradeId, floatingRateIndex) needed for a given financial scenario.
+
+- Data Mapping: Improve accuracy when mapping regulatory or proprietary data fields to FpML standards.-
+
+- Validation: Use semantic similarity to suggest relevant documentation for validation failures.
+
+## 🛠️ Usage with fpml-semantic-search Package
+
+If you are using the official fpml-semantic-search Python package, this model is automatically loaded via the SemanticSearchModel class.
+
+```
+from fpml_semantic_search import StructuralModel, SemanticSearchModel
+from fpml_semantic_search.fpml_structural_model import MOCK_STRUCTURAL_DATA 
+
+# 1. Initialize the Structural Data (Mocking data for demonstration)
+structural_model = StructuralModel(MOCK_STRUCTURAL_DATA)
+
+# 2. Initialize the Semantic Search Model
+# NOTE: This class automatically loads the 'your_username/fpml-semantic-model' 
+# from the Hugging Face Hub (as defined in the source code).
+search_model = SemanticSearchModel(structural_model.data)
+
+# 3. Perform a natural language search
+query = "What element defines the reference rate used for calculating interest payments in a swap?"
+
+results = search_model.semantic_search(query, top_k=3)
+
+print(f"\n--- Semantic Search Results for: '{query}' ---\n")
+for result in results:
+    print(f"[{result['Score']}] Tag: {result['Tag Name']} | Description: {result['Description']}")
+
+# Expected Output (High relevance scores due to fine-tuning):
+# [0.9125] Tag: floatingRateIndex | Description: The benchmark rate (e.g., 'USD-LIBOR-BBA', 'EUR-EONIA-OIS') used for the floating stream.
+# [0.8850] Tag: rateTreatment | Description: Specifies how a mid-market rate is treated, such as 'mid', 'average', or 'interpolated'.
+
+```
+---
+
+## 🚀 Installation
+
+This package requires Python (3.8+).
+
+```bash
+pip install fpml-semantic-model sentence-transformers numpy scipy
+```
+
+Note: The sentence-transformers and numpy/scipy libraries are required for embedding the query and calculating similarity scores, respectively.
+
+## 💡 How It Works
+
+	-Embeddings: The model uses pre-calculated embeddings for FpML element names and their documentation, generated using the highly efficient all-MiniLM-L6-v2 Sentence Transformer model. These embeddings are stored locally in the package's default_embeddings.json file.
+
+	-Search: When a user provides a natural language query (e.g., "details about when the interest rate will be paid"), the model embeds the query and calculates the Cosine Similarity against all stored FpML element vectors.
+
+	-Results: It returns the elements with the highest semantic relevance, ranked by score.
+
+## Direct Sentence-Transformer Loading
+
+You can also load this model directly into any application using the SentenceTransformer library:
+
+```
+from sentence_transformers import SentenceTransformer
+
+MODEL_ID = 'thelocalhost/fpml-semantic-model' 
+model = SentenceTransformer(MODEL_ID)
+
+# Example: Embed a query and compare it to known FpML elements
+query_embedding = model.encode("currency of the notional amount", normalize_embeddings=True)
+```
+
+## Model Details
+
+```
+Attribute	Value
+
+Model ID: thelocalhost/fpml-semantic-model
+Backbone Model: Fine-tuned all-MiniLM-L6-v2 (Sentence Transformers)
+Training Dataset: FpML Element Names and corresponding XSD Documentation Pairs
+Loss Function: Multiple Negatives Ranking Loss (MNR)
+Embedding Dimension: 384
+Similarity Metric: Cosine Similarity
+Performance: Optimized for FpML-specific semantic alignment.
+
+
+Default Data Source	Elements and documentation extracted from core FpML XSD files (provided via default_embeddings.json).
+Use Case	Semantic indexing and retrieval, FpML schema exploration.
+```
+
+## 📚 Training Data Generation
+
+The training dataset was generated using the following methodology:
+
+1. Corpus: All element names and their full XSD documentation strings were extracted from the core FpML schema files.
+
+2. Positive Pairs: A positive pair was defined as (Element Name, Documentation String).
+
+    Example: (tradeId, A unique identifier assigned to the trade by one of the parties.)
+
+3. Fine-Tuning: The model was trained to ensure the vector distance between these positive pairs was minimized, thereby aligning the vector space specifically toward FpML concepts.