Add detailed docstrings and update README with PoC descriptions

README.md

@@ -15,6 +15,7 @@ Friction Flow is an advanced Python-based research project aimed at developing a
 ## Technical Stack
 
  **Python**: Core programming language (version >= 3.12 recommended)
+
 - **PyTorch**: For neural network components and tensor operations
 - **Transformers**: For integration with pre-trained language models
 - **Ray**: For distributed computing
@@ -51,12 +52,49 @@ Friction Flow is an advanced Python-based research project aimed at developing a
 
 - `src/`: Contains the core source code
   - `nfs_story_waves.py`: Simulation components for narrative field dynamics
+  - `nfd_three_story_evolve.py`: Enhanced simulation with three interacting stories
   - `nfs_simple_lab_scenario.py`: Example scenario implementation
   - `language_models.py`: Interfaces for various language models
   - `config.py`: Configuration settings
 - `tests/`: Unit and integration tests
 - `pocs/`: Proof of concept implementations
-- `.github/`: Issue templates and CI/CD workflows
+
+## Latest Proof of Concept Implementations
+
+### nfs_story_waves.py
+
+This PoC implements a quantum-inspired approach to modeling narrative dynamics. Key features include:
+
+- `NarrativeWave`: Represents stories as quantum wave functions in a narrative field.
+- `NarrativeFieldSimulator`: Main class for simulating the evolution of the narrative field.
+- Quantum-inspired operations for story interactions and field evolution.
+- Pattern detection and emergence analysis.
+- Frequency analysis of narrative field dynamics.
+
+This implementation explores the potential of quantum concepts in modeling complex narrative interactions and emergent behaviors.
+
+### nfd_three_story_evolve.py
+
+This PoC focuses on the detailed evolution of three interacting stories within a narrative field. Key components include:
+
+- `Story`: Enhanced representation of individual narratives with emotional states and memory.
+- `StoryPhysics`: Simulates the motion and interactions of stories in the narrative field.
+- `EnhancedCollectiveStoryEngine`: Manages the collective narrative emerging from story interactions.
+- `EnhancedInteractionEngine`: Processes detailed interactions between stories.
+
+This implementation provides a more granular look at story evolution and interaction dynamics.
+
+### nfs_simple_lab_scenario.py
+
+This PoC demonstrates a practical application of the Narrative Field System in a simulated lab environment. Key features include:
+
+- `NarrativeField`: Main class orchestrating the entire system.
+- `FieldAnalyzer`: Analyzes the impact of stories on the field state.
+- `ResonanceDetector`: Finds similarities between stories.
+- `VectorStore`: Manages storage and retrieval of story embeddings.
+- A demo scenario simulating events in a research lab, showcasing how the system can model real-world narrative dynamics.
+
+This implementation showcases how the Narrative Field System can be applied to analyze and track narrative dynamics in a specific context.
 
 ## Development Guidelines
 
@@ -77,6 +115,7 @@ pytest tests/
 ## CI/CD
 
 The project uses GitHub Actions for continuous integration. The workflow includes:
+
 - Setting up Python 3.12.6
 - Installing dependencies
 - Running tests

src/nfd_three_story_evolve.md

@@ -2,27 +2,29 @@
 
 In the quiet hum of the narrative field, three stories drift, each with its own essence, its own silent history. They move, not in straight lines but in subtle, winding trajectories, always pulled by something unseen. This is their story.
 
-**The First Story: “The Waiting Lighthouse”**
+## Stories
 
-The first story has a lighthouse as its core. Its themes are **loneliness** and **enduring duty**. It waits, steady and vigilant, with a soft glow in the field—its core narrative like a beam of light, reaching out. This light, encoded in its **core embedding**, represents its themes of solitude and patience. A quiet sense of **hope** lingers in its memory layer, an echo of past encounters, though that hope has started to fade, losing brightness with time.
+### The First Story: "The Waiting Lighthouse"
+
+The first story has a lighthouse as its core. Its themes are loneliness and enduring duty. It waits, steady and vigilant, with a soft glow in the field—its core narrative like a beam of light, reaching out. This light, encoded in its **core embedding**, represents its themes of solitude and patience. A quiet sense of **hope** lingers in its memory layer, an echo of past encounters, though that hope has started to fade, losing brightness with time.
 
 The lighthouse moves slowly, unhurried. Its **perspective filter** tunes it to notice other stories that carry tones of seeking or loss—stories that might, even if briefly, cross its light. It moves like the light it casts: careful, steady, not actively seeking but ever open to something beyond itself.
 
-**The Second Story: “The Wandering Forest Path”**
+### The Second Story: "The Wandering Forest Path"
 
 The second story is the tale of a traveler lost in a forest, its core theme an **exploration tinged with fear and curiosity**. Its embedding is close to the lighthouse, drawn by a kind of gravitational pull, for the themes of seeking and being found resonate between them. This path has traces of memories from past interactions in the forest—glimpses of fleeting encounters, echoes of other travelers. Its perspective filter is tuned to notice stability and guidance, a longing for direction in its wandering path.
 
 The path moves more restlessly, pulled by hints of guidance in the field. It propels itself through the field as if following shadows, creating ripples in the nearby stories. Each ripple shifts its own embedding slightly, pushing it forward with every new encounter.
 
-**The Third Story: “The Dream of Flight”**
+### The Third Story: "The Dream of Flight"
 
 The third story is light and free—a child’s dream of flying, untethered by gravity. Its embedding holds themes of **freedom, innocence, and boundless wonder**. It hovers nearby, drifting like a leaf on the wind, pulled by currents of curiosity. But in its memories are faint imprints of past encounters with stories grounded and heavy; a slight trace of yearning tints its core.
 
 Its movement is sporadic, darting and circling, unconcerned with direction but deeply responsive to hints of change and connection. Its perspective filter is wide, noticing joy, possibility, and discovery in other stories, even if faint.
 
 ---
 
-## First Encounter: The Lighthouse and the Path**
+## First Encounter: The Lighthouse and the Path
 
 The field, attuned to the proximity of these stories, senses a resonance between the lighthouse and the path, softly adjusting their trajectories. Slowly, they drift closer. The lighthouse, aware of a nearby story with themes of seeking, extends its light, casting a gentle sense of comfort toward the path. The path feels this and pauses, sensing direction in the lighthouse’s presence.
 
@@ -35,7 +37,7 @@ The encounter shifts their **embeddings** slightly:
 
 - The path’s position in semantic space shifts a bit closer to stability, while the lighthouse gains a touch of motion in its otherwise steadfast embedding.
 
-## Second Encounter: The Path and the Dream**
+## Second Encounter: The Path and the Dream
 
 The path, now feeling a faint pull of comfort, continues forward in the field until it senses something playful nearby: the dream of flight. The path is drawn in by the lightness of the dream, and the two stories circle each other, curious but hesitant. The dream of flight feels the path’s echo of hope and seeking, which awakens a new sensation—a hint of groundedness in its own memory layer.
 
@@ -49,7 +51,7 @@ These memories subtly alter their **perspective filters**:
 - The path begins to notice stories with a sense of lightness and play, softening its need for guidance.
 - The dream, meanwhile, gains a slight “weight,” now attuned to stories carrying themes of longing and groundedness.
 
-## Third Encounter: The Collective Shockwave**
+## Third Encounter: The Collective Shockwave
 
 Time passes, and a **pulse** moves through the field. This is a collective event generated by the **Collective Story Engine**—a moment where the narrative field takes on a dominant theme of **seeking connection**. This pulse temporarily heightens each story’s awareness, expanding their perception to even distant stories in the field.