Core Module
===========

The core module provides the main functionality for extracting woseco concept associations from text.

WosecoExtractor Class
---------------------

.. autoclass:: wosecopy.core.WosecoExtractor
   :members:
   :undoc-members:
   :show-inheritance:

   .. automethod:: __init__

Usage Example
-------------

.. code-block:: python

   from wosecopy import WosecoExtractor
   import pandas as pd

   # Initialize extractor
   extractor = WosecoExtractor(language='en', model_size='lg')

   # Process a DataFrame
   df = pd.DataFrame({'Story': ['Once upon a time...']})
   concepts = extractor.get_woseco(df)

   # Process a CSV file
   result_df = extractor.process_csv(
       'input.csv',
       text_column='Story',
       output_path='output.csv'
   )

Key Methods
-----------

get_concept_matches
~~~~~~~~~~~~~~~~~~~

.. automethod:: wosecopy.core.WosecoExtractor.get_concept_matches

Match concepts between consecutive sentences using semantic similarity.

**Algorithm**:

1. Compare all noun pairs between consecutive sentences
2. Calculate similarity using spaCy word embeddings
3. Select pair with maximum similarity
4. Build chain of linked concepts

**Example**:

.. code-block:: python

   concept_list = [
       ['belief', 'village'],
       ['faith', 'people'],
       ['church', 'community']
   ]
   chain = extractor.get_concept_matches(concept_list)
   # Returns: ['belief', 'faith', 'church', 'community']

get_woseco
~~~~~~~~~~

.. automethod:: wosecopy.core.WosecoExtractor.get_woseco

Main function to extract woseco concepts from a DataFrame.

**Process**:

1. Split each story into sentences (by periods)
2. Extract nouns from each sentence
3. Match concepts between consecutive sentences
4. Return list of concept chains

**Example**:

.. code-block:: python

   df = pd.DataFrame({
       'Story': [
           'There was belief. Faith followed.',
           'Music played. Songs filled the air.'
       ]
   })
   concepts = extractor.get_woseco(df)
   # Returns: [['belief', 'faith'], ['music', 'song', 'air']]

extract_nouns
~~~~~~~~~~~~~

.. automethod:: wosecopy.core.WosecoExtractor.extract_nouns

Extract and lemmatize nouns from text.

**Example**:

.. code-block:: python

   text = "The dogs are running in the parks."
   nouns = extractor.extract_nouns(text)
   # Returns: ['dog', 'park']

process_csv
~~~~~~~~~~~

.. automethod:: wosecopy.core.WosecoExtractor.process_csv

End-to-end processing of a CSV file.

**Example**:

.. code-block:: python

   df = extractor.process_csv(
       'stories.csv',
       text_column='Story',
       output_path='results.csv',
       similarity_threshold=0.5
   )