Introduce Narrative Field System with LLM interfaces and CI setup

[leonvanbokhorst]

Summary by Sourcery

Introduce a framework for narrative analysis and tracking using language models, with performance monitoring and logging. Implement interfaces for Ollama and Llama models, and add a caching mechanism for embeddings. Set up CI workflow and logging configuration, and add unit tests for new components.

New Features:

• Introduce a Narrative Field System framework for analyzing and tracking narrative dynamics in complex social systems.
• Implement language model interfaces for Ollama and Llama, providing methods for generating text and embeddings.
• Add a caching mechanism for embeddings to optimize performance.

Enhancements:

• Add performance monitoring and logging capabilities to track system resource usage and operation durations.
• Implement a batch processing system for handling multiple prompts efficiently.

Build:

• Set up a logging configuration to manage log files and handle log rotation.

CI:

• Add a CI workflow to run tests on pull requests for the 'dev' and 'main' branches.

Tests:

• Add unit tests for language model interfaces and embedding cache functionality.

[sourcery-ai]

Reviewer's Guide by Sourcery

This PR introduces a new Narrative Field System (NFS) framework for analyzing and tracking narrative dynamics in social systems. The implementation includes core system components, language model interfaces, and testing infrastructure. The system uses async/await patterns for efficient processing and includes comprehensive logging and performance monitoring.

Class diagram for Narrative Field System

classDiagram
    class VectorStore {
        <<abstract>>
        +store(story: Story, embedding: List[float])
        +find_similar(embedding: List[float], threshold: float, limit: int) List[Dict]
    }

    class Story {
        +content: str
        +context: str
        +id: StoryID
        +timestamp: datetime
        +metadata: Optional[Dict[str, Any]]
        +resonances: List[str]
        +field_effects: List[Dict]
    }

    class FieldState {
        +description: str
        +patterns: List[Dict[str, Any]]
        +active_resonances: List[Dict[str, Any]]
        +emergence_points: List[Dict[str, Any]]
        +timestamp: datetime
    }

    class FieldAnalysisPrompts {
        +get_impact_analysis_prompt(story: Story, current_state: FieldState) str
        +get_pattern_detection_prompt(stories: List[Story], current_state: FieldState) str
        +get_resonance_analysis_prompt(story1: Story, story2: Story) str
    }

    class PerformanceMetrics {
        +metrics: Dict[str, Dict[str, Any]]
        +start_timer(operation: str)
        +stop_timer(operation: str) float
        +get_average_duration(operation: str) float
        +print_summary()
        +log_system_resources()
    }

    class PerformanceMonitor {
        +metrics: List[Dict[str, float]]
        +monitor_generation(llm: LanguageModel, prompt: str) Tuple[str, Dict[str, float]]
        +get_performance_report() Dict[str, float]
    }

    class BatchProcessor {
        +llm: LanguageModel
        +optimal_batch_size: int
        +process_batch(prompts: List[str]) List[str]
    }

    class ChromaStore {
        +collection: Any
        +store(story: Story, embedding: List[float])
        +find_similar(embedding: List[float], threshold: float, limit: int) List[Dict]
    }

    class FieldAnalyzer {
        +llm: LanguageModel
        +analyze_impact(story: Story, current_state: FieldState) Dict[str, Any]
        +detect_patterns(stories: List[Story], current_state: FieldState) str
    }

    class ResonanceDetector {
        +vector_store: VectorStore
        +llm: LanguageModel
        +find_resonances(story: Story, threshold: float, limit: int) List[Dict[str, Any]]
        +determine_resonance_type(story1: Story, story2: Story) Dict[str, Any]
    }

    class NarrativeField {
        +_analyzer: FieldAnalyzer
        +_resonance_detector: ResonanceDetector
        +_vector_store: VectorStore
        +_state: FieldState
        +_stories: Dict[StoryID, Story]
        +add_story(content: str, context: str) Story
    }

    VectorStore <|-- ChromaStore
    NarrativeField --> FieldAnalyzer
    NarrativeField --> ResonanceDetector
    NarrativeField --> VectorStore
    FieldAnalyzer --> LanguageModel
    ResonanceDetector --> LanguageModel
    ResonanceDetector --> VectorStore
    BatchProcessor --> LanguageModel
    PerformanceMonitor --> LanguageModel
    Story --> FieldState
    FieldAnalysisPrompts --> Story
    FieldAnalysisPrompts --> FieldState
    PerformanceMetrics --> Story
    PerformanceMetrics --> FieldState

Loading

Class diagram for Language Models

classDiagram
    class LanguageModel {
        <<abstract>>
        +generate(prompt: str) str
        +_generate_embedding(text: str) List[float]
        +generate_embedding(text: str) List[float]
        +cleanup()
    }

    class OllamaInterface {
        +generate(prompt: str) str
        +_generate_embedding(text: str) List[float]
    }

    class LlamaInterface {
        +generate(prompt: str) str
        +_generate_embedding(text: str) List[float]
        +cleanup()
    }

    LanguageModel <|-- OllamaInterface
    LanguageModel <|-- LlamaInterface
    OllamaInterface --> EmbeddingCache
    LlamaInterface --> EmbeddingCache
    LanguageModel --> EmbeddingCache

Loading

File-Level Changes

Change	Details	Files
Implements the core Narrative Field System framework with story processing and field analysis capabilities	Creates Story and FieldState dataclasses for managing narrative data Implements field analysis prompts for impact, pattern detection, and resonance analysis Adds performance monitoring and metrics tracking Implements batch processing with dynamic size adjustment Creates vector store integration using ChromaDB	src/nfs_simple_lab_scenario.py
Implements language model interfaces with support for multiple LLM backends	Creates abstract LanguageModel base class Implements OllamaInterface for Ollama integration Implements LlamaInterface for local LLM usage Adds error handling and async support Implements embedding generation and caching	src/language_models.py
Adds testing infrastructure and proof of concept implementations	Creates comprehensive tests for language model interfaces Implements embedding cache tests Adds proof of concept for bias research Implements async processing demonstration	tests/test_language_models.py tests/test_embedding_cache.py pocs/nfs_bias_research.py pocs/poc_async.py
Implements configuration and logging infrastructure	Creates configuration system with model settings Implements logging setup with rotation and cleanup Adds embedding cache implementation Sets up development and production logging paths	src/config.py src/logging_config.py src/embedding_cache.py

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time. You can also use
  this command to specify where the summary should be inserted.

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey @leonvanbokhorst - I've reviewed your changes - here's some feedback:

Overall Comments:

• Consider adding more test coverage, particularly for the NarrativeField and VectorStore components which currently lack tests.

Here's what I looked at during the review

• 🟡 General issues: 1 issue found
• 🟢 Security: all looks good
• 🟡 Testing: 2 issues found
• 🟡 Complexity: 1 issue found
• 🟢 Documentation: all looks good

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[leonvanbokhorst]

@sourcery-ai merge PR