brain-system 0.1.0__tar.gz

brain_system-0.1.0/.env.example

@@ -0,0 +1,10 @@
+# Example environment configuration
+# Copy this file to .env and fill in your API keys
+
+# Required for Gemini provider
+# GOOGLE_API_KEY=your_google_api_key_here
+
+# Required for OpenAI provider
+# OPENAI_API_KEY=your_openai_api_key_here
+
+# Ollama requires no API key — just install Ollama and pull a model

brain_system-0.1.0/.gitignore

@@ -0,0 +1,28 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+dist/
+build/
+*.egg
+
+# Environment
+.env
+.venv/
+venv/
+env/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Project-specific
+brain_memory.json
+brain_system/uploads/
+*.pdf

brain_system-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Brain System Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

brain_system-0.1.0/MANIFEST.in

@@ -0,0 +1,2 @@
+recursive-include brain_system/web *
+include brain_system/py.typed

brain_system-0.1.0/PKG-INFO

@@ -0,0 +1,278 @@
+Metadata-Version: 2.4
+Name: brain-system
+Version: 0.1.0
+Summary: A multi-agent cognitive architecture powered by LangGraph — five specialized AI agents modeled after the human brain.
+Project-URL: Homepage, https://github.com/shivamtyagi18/BRAIN
+Project-URL: Repository, https://github.com/shivamtyagi18/BRAIN
+Project-URL: Issues, https://github.com/shivamtyagi18/BRAIN/issues
+Author-email: Shivam Tyagi <shivamtyagi18@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: agents,ai,brain,cognitive,langchain,langgraph,multi-agent
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: langchain
+Requires-Dist: langchain-community
+Requires-Dist: langchain-core
+Requires-Dist: langchain-google-genai
+Requires-Dist: langchain-ollama
+Requires-Dist: langchain-openai
+Requires-Dist: langgraph
+Requires-Dist: pypdf2
+Requires-Dist: python-dotenv
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Provides-Extra: web
+Requires-Dist: flask; extra == 'web'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# 🧠 Brain System
+
+### A Multi-Agent Cognitive Architecture Powered by LangGraph
+
+*Five specialized AI agents — modeled after the human brain — collaborate to process your input and generate thoughtful, nuanced responses.*
+
+[![Python 3.10+](https://img.shields.io/badge/Python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![PyPI](https://img.shields.io/pypi/v/brain-system.svg)](https://pypi.org/project/brain-system/)
+[![LangGraph](https://img.shields.io/badge/Built%20with-LangGraph-orange.svg)](https://github.com/langchain-ai/langgraph)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+</div>
+
+---
+
+## 🧩 How It Works
+
+Brain System maps biological brain functions to specialized AI agents that process every input in parallel — just like the human brain:
+
+```mermaid
+graph LR
+    A[User Input] --> B[🔵 Sensory Agent<br>Thalamus]
+    B --> C[🟣 Memory Agent<br>Hippocampus]
+    B --> D[🟢 Logic Agent<br>Frontal Lobe]
+    B --> E[🔴 Emotional Agent<br>Amygdala]
+    C --> F[🟡 Executive Agent<br>Prefrontal Cortex]
+    D --> F
+    E --> F
+    F --> G[Final Response]
+```
+
+| Agent | Brain Analog | What It Does |
+|:------|:-------------|:-------------|
+| **Sensory** | Thalamus & Sensory Cortex | Multi-layer signal classification, pattern recognition, salience detection |
+| **Memory** | Hippocampus & DLPFC | LLM-driven contextual synthesis, associative linking, temporal weighting |
+| **Logic** | Left Frontal Lobe & DLPFC | Deductive/inductive reasoning, fallacy detection, counter-arguments |
+| **Emotional** | Amygdala, Insula & Cingulate | Emotional profiling, empathy reading, ethical safety checks |
+| **Executive** | Full Prefrontal Cortex | Conflict resolution between agents, response calibration, integrated output |
+
+## 🎭 Persona Mode
+
+Upload a biography or autobiography, and the entire Brain responds **as that person would**.
+
+The system extracts personality traits, speech patterns, reasoning style, and emotional tendencies — then injects tailored context into each agent. The Logic Agent thinks in their reasoning style, the Emotional Agent mirrors their emotional tendencies, and the Executive Agent speaks in their voice.
+
+> **Example:** Upload Nelson Mandela's autobiography → ask about dealing with conflict → get a response reflecting his values of reconciliation, strategic patience, and ubuntu philosophy.
+
+## 📦 Install
+
+```bash
+pip install brain-system
+```
+
+> For the web UI, install the optional extra: `pip install brain-system[web]`
+
+## 🚀 Quick Start — Library Usage
+
+```python
+from brain_system import BrainWrapper
+
+# Create a Brain (choose provider: "gemini", "openai", or "ollama")
+brain = BrainWrapper(provider="ollama", model_name="mistral")
+
+# Process input through all 5 agents
+result = brain.think("What is the meaning of justice?")
+
+# Get the final synthesized response
+print(result.response)
+
+# Inspect individual agent signals
+print(result.sensory)     # Thalamus — input classification
+print(result.memory)      # Hippocampus — memory context
+print(result.logic)       # Frontal Lobe — logical analysis
+print(result.emotional)   # Amygdala — emotional analysis
+```
+
+### Persona Mode
+
+```python
+brain.load_persona("gandhi_autobiography.pdf")
+result = brain.think("How should we deal with injustice?")
+print(result.response)    # Responds in Gandhi's voice
+
+brain.clear_persona()     # Revert to default
+```
+
+### Memory Management
+
+```python
+# Custom memory file location
+brain = BrainWrapper(provider="gemini", memory_path="./my_memory.json")
+
+# Clear all stored memories
+brain.clear_memory()
+```
+
+### API Reference
+
+| Class / Method | Description |
+|:---|:---|
+| `BrainWrapper(provider, model_name, memory_path)` | Create a Brain instance |
+| `.think(input) → BrainResult` | Process input through the 5-agent pipeline |
+| `.load_persona(filepath)` | Load a persona from `.txt` or `.pdf` |
+| `.clear_persona()` | Remove the active persona |
+| `.clear_memory()` | Erase all long-term memories |
+| `.persona_active` | `bool` — is a persona loaded? |
+| `.persona_name` | Name of the active persona |
+| `BrainResult.response` | Final synthesized response |
+| `BrainResult.agent_signals` | `dict` of each agent's raw output |
+| `BrainResult.sensory / .memory / .logic / .emotional` | Shortcut accessors |
+
+See [`examples/`](examples/) for complete usage scripts.
+
+---
+
+## 🖥️ Development Setup
+
+### Clone & Install
+
+```bash
+git clone https://github.com/shivamtyagi18/BRAIN.git
+cd BRAIN
+pip install -e ".[web,dev]"
+```
+
+### Configure (Optional)
+
+Create a `.env` file in the project root for cloud providers:
+
+```env
+# Only needed if using Gemini or OpenAI
+GOOGLE_API_KEY=your_key_here
+OPENAI_API_KEY=your_key_here
+```
+
+> **No API key needed for Ollama** — runs entirely on your local machine.
+
+### Run
+
+#### Web UI
+```bash
+python -m brain_system.app
+```
+Open **http://localhost:5001** in your browser.
+
+#### Command Line
+```bash
+brain-cli
+```
+
+## 🖥️ Web Interface
+
+The web UI features:
+- **Provider selection** — choose Gemini, OpenAI, or Ollama at startup
+- **Persona upload** — drag & drop a `.txt` or `.pdf` biography
+- **Live chat** — dark-mode interface with agent activity indicators
+- **Agent transparency** — expand each agent's internal reasoning with "Show agent signals"
+- **Mid-conversation persona switching** — change or clear persona without restarting
+- **New Chat** — full reset button to start fresh
+- **Clear Memory** — wipe stored memories without restarting
+
+## 🤖 Supported LLM Providers
+
+| Provider | Requirements | Best For |
+|:---------|:-------------|:---------|
+| **Ollama** | [Ollama](https://ollama.ai) installed locally | Privacy, offline use, no cost |
+| **Gemini** | `GOOGLE_API_KEY` in `.env` | High-quality responses |
+| **OpenAI** | `OPENAI_API_KEY` in `.env` | GPT-4 class models |
+
+### Using Ollama (Local)
+
+```bash
+# Install Ollama, then pull a model:
+ollama pull mistral
+
+# For uncensored output, try:
+ollama pull dolphin-mistral
+```
+
+## 📁 Project Structure
+
+```
+brain-system/
+├── pyproject.toml                  # Package config & dependencies
+├── run.sh                          # Single-command launcher
+├── examples/
+│   ├── basic_usage.py              # Minimal library usage
+│   ├── persona_mode.py             # Persona loading example
+│   └── custom_provider.py          # Provider switching example
+└── brain_system/
+    ├── __init__.py                 # Public API exports
+    ├── wrapper.py                  # BrainWrapper — developer entry point
+    ├── app.py                      # Flask web server (optional)
+    ├── main.py                     # CLI entry point
+    ├── agents/
+    │   ├── base_agent.py           # Abstract base with persona injection
+    │   ├── sensory_agent.py        # Input parsing (Thalamus)
+    │   ├── memory_agent.py         # Context retrieval (Hippocampus)
+    │   ├── emotional_agent.py      # Sentiment analysis (Amygdala)
+    │   ├── logic_agent.py          # Reasoning (Frontal Lobe)
+    │   └── executive_agent.py      # Decision synthesis (PFC)
+    ├── core/
+    │   ├── orchestrator.py         # LangGraph workflow engine
+    │   ├── llm_interface.py        # Multi-provider LLM factory
+    │   ├── memory_store.py         # Persistent memory (JSON)
+    │   ├── document_loader.py      # TXT/PDF document ingestion
+    │   └── persona.py              # Persona extraction & injection
+    └── web/
+        ├── templates/index.html    # Chat interface
+        └── static/
+            ├── css/style.css       # Dark-mode theme
+            └── js/app.js           # Frontend logic
+```
+
+## 🔧 Architecture Highlights
+
+- **LangGraph Orchestration** — Agents run as nodes in a compiled state graph with parallel execution for Memory, Logic, and Emotional processing
+- **Modular LLM Factory** — Swap providers with a single parameter; no code changes needed
+- **Dual Memory** — Short-term (conversation context) + Long-term (persistent JSON store with keyword retrieval)
+- **Persona Injection** — Role-specific context: each agent gets *different* aspects of the persona profile tailored to its function
+
+## 🤝 Contributing
+
+Contributions are welcome! Some ideas:
+
+- **Vector memory** — Replace JSON keyword search with embedding-based retrieval
+- **Additional agents** — Add a Creativity Agent, Social Agent, or Moral Reasoning Agent
+- **Streaming responses** — Real-time token streaming in the web UI
+- **Multi-turn persona** — Let the persona evolve based on the conversation
+- **Voice interface** — Add speech-to-text input and text-to-speech output
+
+## 📝 License
+
+MIT License — see [LICENSE](LICENSE) for details.
+
+---
+
+<div align="center">
+<i>Built with 🧠 by mapping neuroscience to multi-agent AI</i>
+</div>

brain_system-0.1.0/README.md

@@ -0,0 +1,242 @@
+<div align="center">
+
+# 🧠 Brain System
+
+### A Multi-Agent Cognitive Architecture Powered by LangGraph
+
+*Five specialized AI agents — modeled after the human brain — collaborate to process your input and generate thoughtful, nuanced responses.*
+
+[![Python 3.10+](https://img.shields.io/badge/Python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![PyPI](https://img.shields.io/pypi/v/brain-system.svg)](https://pypi.org/project/brain-system/)
+[![LangGraph](https://img.shields.io/badge/Built%20with-LangGraph-orange.svg)](https://github.com/langchain-ai/langgraph)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+</div>
+
+---
+
+## 🧩 How It Works
+
+Brain System maps biological brain functions to specialized AI agents that process every input in parallel — just like the human brain:
+
+```mermaid
+graph LR
+    A[User Input] --> B[🔵 Sensory Agent<br>Thalamus]
+    B --> C[🟣 Memory Agent<br>Hippocampus]
+    B --> D[🟢 Logic Agent<br>Frontal Lobe]
+    B --> E[🔴 Emotional Agent<br>Amygdala]
+    C --> F[🟡 Executive Agent<br>Prefrontal Cortex]
+    D --> F
+    E --> F
+    F --> G[Final Response]
+```
+
+| Agent | Brain Analog | What It Does |
+|:------|:-------------|:-------------|
+| **Sensory** | Thalamus & Sensory Cortex | Multi-layer signal classification, pattern recognition, salience detection |
+| **Memory** | Hippocampus & DLPFC | LLM-driven contextual synthesis, associative linking, temporal weighting |
+| **Logic** | Left Frontal Lobe & DLPFC | Deductive/inductive reasoning, fallacy detection, counter-arguments |
+| **Emotional** | Amygdala, Insula & Cingulate | Emotional profiling, empathy reading, ethical safety checks |
+| **Executive** | Full Prefrontal Cortex | Conflict resolution between agents, response calibration, integrated output |
+
+## 🎭 Persona Mode
+
+Upload a biography or autobiography, and the entire Brain responds **as that person would**.
+
+The system extracts personality traits, speech patterns, reasoning style, and emotional tendencies — then injects tailored context into each agent. The Logic Agent thinks in their reasoning style, the Emotional Agent mirrors their emotional tendencies, and the Executive Agent speaks in their voice.
+
+> **Example:** Upload Nelson Mandela's autobiography → ask about dealing with conflict → get a response reflecting his values of reconciliation, strategic patience, and ubuntu philosophy.
+
+## 📦 Install
+
+```bash
+pip install brain-system
+```
+
+> For the web UI, install the optional extra: `pip install brain-system[web]`
+
+## 🚀 Quick Start — Library Usage
+
+```python
+from brain_system import BrainWrapper
+
+# Create a Brain (choose provider: "gemini", "openai", or "ollama")
+brain = BrainWrapper(provider="ollama", model_name="mistral")
+
+# Process input through all 5 agents
+result = brain.think("What is the meaning of justice?")
+
+# Get the final synthesized response
+print(result.response)
+
+# Inspect individual agent signals
+print(result.sensory)     # Thalamus — input classification
+print(result.memory)      # Hippocampus — memory context
+print(result.logic)       # Frontal Lobe — logical analysis
+print(result.emotional)   # Amygdala — emotional analysis
+```
+
+### Persona Mode
+
+```python
+brain.load_persona("gandhi_autobiography.pdf")
+result = brain.think("How should we deal with injustice?")
+print(result.response)    # Responds in Gandhi's voice
+
+brain.clear_persona()     # Revert to default
+```
+
+### Memory Management
+
+```python
+# Custom memory file location
+brain = BrainWrapper(provider="gemini", memory_path="./my_memory.json")
+
+# Clear all stored memories
+brain.clear_memory()
+```
+
+### API Reference
+
+| Class / Method | Description |
+|:---|:---|
+| `BrainWrapper(provider, model_name, memory_path)` | Create a Brain instance |
+| `.think(input) → BrainResult` | Process input through the 5-agent pipeline |
+| `.load_persona(filepath)` | Load a persona from `.txt` or `.pdf` |
+| `.clear_persona()` | Remove the active persona |
+| `.clear_memory()` | Erase all long-term memories |
+| `.persona_active` | `bool` — is a persona loaded? |
+| `.persona_name` | Name of the active persona |
+| `BrainResult.response` | Final synthesized response |
+| `BrainResult.agent_signals` | `dict` of each agent's raw output |
+| `BrainResult.sensory / .memory / .logic / .emotional` | Shortcut accessors |
+
+See [`examples/`](examples/) for complete usage scripts.
+
+---
+
+## 🖥️ Development Setup
+
+### Clone & Install
+
+```bash
+git clone https://github.com/shivamtyagi18/BRAIN.git
+cd BRAIN
+pip install -e ".[web,dev]"
+```
+
+### Configure (Optional)
+
+Create a `.env` file in the project root for cloud providers:
+
+```env
+# Only needed if using Gemini or OpenAI
+GOOGLE_API_KEY=your_key_here
+OPENAI_API_KEY=your_key_here
+```
+
+> **No API key needed for Ollama** — runs entirely on your local machine.
+
+### Run
+
+#### Web UI
+```bash
+python -m brain_system.app
+```
+Open **http://localhost:5001** in your browser.
+
+#### Command Line
+```bash
+brain-cli
+```
+
+## 🖥️ Web Interface
+
+The web UI features:
+- **Provider selection** — choose Gemini, OpenAI, or Ollama at startup
+- **Persona upload** — drag & drop a `.txt` or `.pdf` biography
+- **Live chat** — dark-mode interface with agent activity indicators
+- **Agent transparency** — expand each agent's internal reasoning with "Show agent signals"
+- **Mid-conversation persona switching** — change or clear persona without restarting
+- **New Chat** — full reset button to start fresh
+- **Clear Memory** — wipe stored memories without restarting
+
+## 🤖 Supported LLM Providers
+
+| Provider | Requirements | Best For |
+|:---------|:-------------|:---------|
+| **Ollama** | [Ollama](https://ollama.ai) installed locally | Privacy, offline use, no cost |
+| **Gemini** | `GOOGLE_API_KEY` in `.env` | High-quality responses |
+| **OpenAI** | `OPENAI_API_KEY` in `.env` | GPT-4 class models |
+
+### Using Ollama (Local)
+
+```bash
+# Install Ollama, then pull a model:
+ollama pull mistral
+
+# For uncensored output, try:
+ollama pull dolphin-mistral
+```
+
+## 📁 Project Structure
+
+```
+brain-system/
+├── pyproject.toml                  # Package config & dependencies
+├── run.sh                          # Single-command launcher
+├── examples/
+│   ├── basic_usage.py              # Minimal library usage
+│   ├── persona_mode.py             # Persona loading example
+│   └── custom_provider.py          # Provider switching example
+└── brain_system/
+    ├── __init__.py                 # Public API exports
+    ├── wrapper.py                  # BrainWrapper — developer entry point
+    ├── app.py                      # Flask web server (optional)
+    ├── main.py                     # CLI entry point
+    ├── agents/
+    │   ├── base_agent.py           # Abstract base with persona injection
+    │   ├── sensory_agent.py        # Input parsing (Thalamus)
+    │   ├── memory_agent.py         # Context retrieval (Hippocampus)
+    │   ├── emotional_agent.py      # Sentiment analysis (Amygdala)
+    │   ├── logic_agent.py          # Reasoning (Frontal Lobe)
+    │   └── executive_agent.py      # Decision synthesis (PFC)
+    ├── core/
+    │   ├── orchestrator.py         # LangGraph workflow engine
+    │   ├── llm_interface.py        # Multi-provider LLM factory
+    │   ├── memory_store.py         # Persistent memory (JSON)
+    │   ├── document_loader.py      # TXT/PDF document ingestion
+    │   └── persona.py              # Persona extraction & injection
+    └── web/
+        ├── templates/index.html    # Chat interface
+        └── static/
+            ├── css/style.css       # Dark-mode theme
+            └── js/app.js           # Frontend logic
+```
+
+## 🔧 Architecture Highlights
+
+- **LangGraph Orchestration** — Agents run as nodes in a compiled state graph with parallel execution for Memory, Logic, and Emotional processing
+- **Modular LLM Factory** — Swap providers with a single parameter; no code changes needed
+- **Dual Memory** — Short-term (conversation context) + Long-term (persistent JSON store with keyword retrieval)
+- **Persona Injection** — Role-specific context: each agent gets *different* aspects of the persona profile tailored to its function
+
+## 🤝 Contributing
+
+Contributions are welcome! Some ideas:
+
+- **Vector memory** — Replace JSON keyword search with embedding-based retrieval
+- **Additional agents** — Add a Creativity Agent, Social Agent, or Moral Reasoning Agent
+- **Streaming responses** — Real-time token streaming in the web UI
+- **Multi-turn persona** — Let the persona evolve based on the conversation
+- **Voice interface** — Add speech-to-text input and text-to-speech output
+
+## 📝 License
+
+MIT License — see [LICENSE](LICENSE) for details.
+
+---
+
+<div align="center">
+<i>Built with 🧠 by mapping neuroscience to multi-agent AI</i>
+</div>

brain_system-0.1.0/brain_system/__init__.py

@@ -0,0 +1,29 @@
+"""Brain System — Multi-Agent Cognitive Architecture powered by LangGraph.
+
+Five specialised AI agents — modelled after the human brain — collaborate
+to process input and generate thoughtful, nuanced responses.
+
+Quick start::
+
+    from brain_system import BrainWrapper
+
+    brain = BrainWrapper(provider="openai")
+    result = brain.think("What is justice?")
+    print(result.response)
+"""
+
+__version__ = "0.1.0"
+
+from brain_system.wrapper import BrainWrapper, BrainResult  # noqa: F401
+from brain_system.core.orchestrator import BrainOrchestrator  # noqa: F401
+from brain_system.core.llm_interface import LLMFactory  # noqa: F401
+from brain_system.agents.base_agent import BaseAgent  # noqa: F401
+
+__all__ = [
+    "BrainWrapper",
+    "BrainResult",
+    "BrainOrchestrator",
+    "LLMFactory",
+    "BaseAgent",
+    "__version__",
+]

brain_system-0.1.0/brain_system/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running with: python -m brain_system"""
+from brain_system.app import run_server
+
+if __name__ == "__main__":
+    run_server()

brain_system-0.1.0/brain_system/agents/base_agent.py

@@ -0,0 +1,37 @@
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict, List
+from langchain_core.messages import HumanMessage, SystemMessage
+from ..core.llm_interface import LLMFactory
+
+class BaseAgent(ABC):
+    def __init__(self, name: str, role: str, provider: str = "gemini", model_name: str = None):
+        self.name = name
+        self.role = role
+        self.persona_context: str = ""  # Injected by orchestrator when persona is active
+        self.llm = LLMFactory.create_llm(provider=provider, model_name=model_name)
+    
+    @abstractmethod
+    def process(self, inputs: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Process the input dictionary and return a result dictionary.
+        Must be implemented by subclasses.
+        """
+        pass
+
+    def _query_llm(self, system_prompt: str, user_input: str) -> str:
+        """
+        Helper method to query the LLM with a system and user message.
+        Prepends persona context if active.
+        """
+        full_prompt = system_prompt
+        if self.persona_context:
+            full_prompt = self.persona_context + "\n\n" + system_prompt
+
+        messages = [
+            SystemMessage(content=full_prompt),
+            HumanMessage(content=user_input)
+        ]
+        response = self.llm.invoke(messages)
+        return response.content
+