dialograph 0.3.0__tar.gz

dialograph-0.3.0/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: dialograph
+Version: 0.3.0
+Summary: Dialograph is a Python toolkit for building, evolving, and reasoning over temporal dialogue graphs for proactive conversational agents.
+Author: author
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: networkx>=3.6.1
+Requires-Dist: numpy>=2.4.0
+Requires-Dist: pydantic>=2.12.5
+
+# dialograph
+
+**Dialograph** is a lightweight Python library for representing, evolving, and traversing dialogue memory as a temporal graph.
+It is designed for **proactive dialogue agents**, where reasoning over user preferences, beliefs, and strategies matters more than raw generation.
+
+At its core, Dialograph wraps a dynamic graph structure around typed dialogue memories and provides clean hooks for retrieval, scoring, and long-term evolution.
+
+---
+
+## Core Concepts
+
+### Nodes
+
+Nodes represent dialogue memory units such as:
+
+* user preferences
+* beliefs / facts
+* dialogue strategies
+
+Each node carries a **state object** (e.g. `PreferenceState`, `BeliefState`) with confidence and temporal metadata.
+
+### Edges
+
+Edges represent relations between memory units:
+
+* semantic relations (supports, contradicts, elicits)
+* dialogue flow dependencies
+* strategy activation paths
+
+Edges are directional, weighted, and time-aware.
+
+### Time
+
+Dialograph maintains an internal time counter that allows:
+
+* decay of confidence
+* forgetting
+* recency-based retrieval
+
+---
+
+## Project Structure
+
+```text
+dialograph/
+├── core/               # graph primitives
+│   ├── graph.py        # Dialograph wrapper
+│   ├── node.py         # node state definitions
+│   └── edge.py         # edge state definitions
+│
+├── memory/             # typed dialogue memory
+│   ├── preference.py
+│   ├── belief.py
+│   └── strategy.py
+│
+├── traversal/          # retrieval and scoring
+│   ├── retrieve.py
+│   └── score.py
+│
+├── utils/              # persistence & visualization
+│   ├── io.py
+│   └── visualize.py
+```
+
+---
+
+## Installation
+
+For development:
+```bash
+git clone https://github.com/nabin2004/dialograph.git
+```
+
+```bash
+cd dialograph
+```
+
+```bash
+uv venv
+```
+```bash
+source .venv/bin/activate
+```
+
+```bash
+uv pip install -e .
+```
+
+---
+
+## Quick Example
+
+```python
+from dialograph.core.graph import Dialograph
+from dialograph.memory.preference import PreferenceState
+from dialograph.core.edge import EdgeState
+
+g = Dialograph()
+
+g.add_node(
+    "pref_movie",
+    state=PreferenceState(
+        key="movie_genre",
+        value="sci-fi",
+        confidence=0.9,
+    )
+)
+
+g.add_node(
+    "belief_stress",
+    state=BeliefState(
+        proposition="user is stressed about exams",
+        confidence=0.7,
+    )
+)
+
+g.add_edge(
+    "belief_stress",
+    "pref_movie",
+    state=EdgeState(relation="influences")
+)
+```
+
+---
+
+## Intended Use Cases
+
+* Proactive dialogue systems
+* Emotional support agents
+* Preference elicitation
+* Strategy planning and reuse
+* Dialogue memory research
+
+---
+
+## Status
+
+This project is **under active development**.
+APIs may evolve, but core abstractions are expected to remain stable.
+
+---
+
+## Roadmap
+
+* [ ] Path-based retrieval
+* [ ] Forgetting thresholds
+* [ ] Graph serialization
+* [ ] 3D / interactive visualization
+* [ ] LLM-facing retrieval API
+
+---
+
+## License
+
+MIT License.
+
+---
+
+## Citation
+
+If you use Dialograph in academic work, please cite the corresponding paper (coming soon).
+

dialograph-0.3.0/README.md

@@ -0,0 +1,162 @@
+# dialograph
+
+**Dialograph** is a lightweight Python library for representing, evolving, and traversing dialogue memory as a temporal graph.
+It is designed for **proactive dialogue agents**, where reasoning over user preferences, beliefs, and strategies matters more than raw generation.
+
+At its core, Dialograph wraps a dynamic graph structure around typed dialogue memories and provides clean hooks for retrieval, scoring, and long-term evolution.
+
+---
+
+## Core Concepts
+
+### Nodes
+
+Nodes represent dialogue memory units such as:
+
+* user preferences
+* beliefs / facts
+* dialogue strategies
+
+Each node carries a **state object** (e.g. `PreferenceState`, `BeliefState`) with confidence and temporal metadata.
+
+### Edges
+
+Edges represent relations between memory units:
+
+* semantic relations (supports, contradicts, elicits)
+* dialogue flow dependencies
+* strategy activation paths
+
+Edges are directional, weighted, and time-aware.
+
+### Time
+
+Dialograph maintains an internal time counter that allows:
+
+* decay of confidence
+* forgetting
+* recency-based retrieval
+
+---
+
+## Project Structure
+
+```text
+dialograph/
+├── core/               # graph primitives
+│   ├── graph.py        # Dialograph wrapper
+│   ├── node.py         # node state definitions
+│   └── edge.py         # edge state definitions
+│
+├── memory/             # typed dialogue memory
+│   ├── preference.py
+│   ├── belief.py
+│   └── strategy.py
+│
+├── traversal/          # retrieval and scoring
+│   ├── retrieve.py
+│   └── score.py
+│
+├── utils/              # persistence & visualization
+│   ├── io.py
+│   └── visualize.py
+```
+
+---
+
+## Installation
+
+For development:
+```bash
+git clone https://github.com/nabin2004/dialograph.git
+```
+
+```bash
+cd dialograph
+```
+
+```bash
+uv venv
+```
+```bash
+source .venv/bin/activate
+```
+
+```bash
+uv pip install -e .
+```
+
+---
+
+## Quick Example
+
+```python
+from dialograph.core.graph import Dialograph
+from dialograph.memory.preference import PreferenceState
+from dialograph.core.edge import EdgeState
+
+g = Dialograph()
+
+g.add_node(
+    "pref_movie",
+    state=PreferenceState(
+        key="movie_genre",
+        value="sci-fi",
+        confidence=0.9,
+    )
+)
+
+g.add_node(
+    "belief_stress",
+    state=BeliefState(
+        proposition="user is stressed about exams",
+        confidence=0.7,
+    )
+)
+
+g.add_edge(
+    "belief_stress",
+    "pref_movie",
+    state=EdgeState(relation="influences")
+)
+```
+
+---
+
+## Intended Use Cases
+
+* Proactive dialogue systems
+* Emotional support agents
+* Preference elicitation
+* Strategy planning and reuse
+* Dialogue memory research
+
+---
+
+## Status
+
+This project is **under active development**.
+APIs may evolve, but core abstractions are expected to remain stable.
+
+---
+
+## Roadmap
+
+* [ ] Path-based retrieval
+* [ ] Forgetting thresholds
+* [ ] Graph serialization
+* [ ] 3D / interactive visualization
+* [ ] LLM-facing retrieval API
+
+---
+
+## License
+
+MIT License.
+
+---
+
+## Citation
+
+If you use Dialograph in academic work, please cite the corresponding paper (coming soon).
+

dialograph-0.3.0/pyproject.toml

@@ -0,0 +1,32 @@
+[project]
+name = "dialograph"
+version = "0.3.0"
+description = "Dialograph is a Python toolkit for building, evolving, and reasoning over temporal dialogue graphs for proactive conversational agents."
+readme = "README.md"
+requires-python = ">=3.11"
+authors = [
+    { name = "author" }
+]
+dependencies = [
+    "networkx>=3.6.1",
+    "numpy>=2.4.0",
+    "pydantic>=2.12.5",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/dialograph"]
+
+#[tool.uv.extra-build-dependencies]
+cchardet = ["cython"]
+
+[dependency-groups]
+dev = [
+    "black>=25.12.0",
+    "mkdocs>=1.6.1",
+    "mkdocs-material>=9.7.1",
+    "mkdocstrings[python]>=1.0.0",
+    "mypy>=1.19.1",
+    "pre-commit>=4.5.1",
+    "pytest>=9.0.2",
+    "ruff>=0.14.10",
+]

dialograph-0.3.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

dialograph-0.3.0/src/dialograph/__init__.py

@@ -0,0 +1,4 @@
+from .core.node import Node
+from .core.edge import Edge
+
+__all__ = ["Node", "Edge"]

dialograph-0.3.0/src/dialograph/agent/agent.py

@@ -0,0 +1,58 @@
+from typing import Any
+
+from langchain_openai import ChatOpenAI
+from langchain_core.prompts import ChatPromptTemplate, SystemMessagePromptTemplate, HumanMessagePromptTemplate, AIMessagePromptTemplate
+
+class Agent:
+    def __init__(self, args):
+        self.args = args
+        self.cost = 0 
+    
+    def next_action(self, conversation) -> str:
+        raise NotImplementedError("Subclasses must implement this method.")
+        
+    def generate_prompt(self, prompt_template: dict[str, Any]) -> ChatPromptTemplate:
+        messages = []
+        messages.append(SystemMessagePromptTemplate.from_template(prompt_template["system"]))
+        if "assistant" in prompt_template:
+            messages.append(AIMessagePromptTemplate.from_template(prompt_template["assistant"]))    
+        if "user" in prompt_template:
+            messages.append(HumanMessagePromptTemplate.from_template(prompt_template["user"]))
+        final_prompt_template = ChatPromptTemplate.from_messages(messages)
+        return final_prompt_template
+        
+
+class DialographAgent:
+    """
+    Main agent class: proactive, curriculum-aware dialogue.
+    Integrates graph memory + temporal dynamics + policy.
+    """    
+    def __init__(self, args):
+        self.data_name = args.data_name
+        self.api_key = args.api_key
+        self.args = args 
+        self.mode = args.mode 
+        self.activate_top_k = args.activate_top_k
+        self.activated_memory_nodes = []
+        self.recontextualized_guidance = []
+        
+    def next_action(self, conversation) -> str:
+        pass 
+
+    def revision(self, conversation) -> str:
+        pass
+
+    def extract_from_failure(self, conversation) -> str:
+        pass
+
+    def extract_from_success(self, conversation) -> str:
+        pass
+
+    def retrieve_nodes(self, conversation) -> str:
+        pass
+
+    def reinterpretation(self, conversation) -> str:
+        pass
+
+    def save_nodes(self, conversation) -> str:
+        pass

dialograph-0.3.0/src/dialograph/agent/policy.py

@@ -0,0 +1,76 @@
+from enum import Enum
+from typing import Optional, Tuple
+from ..core.node import TemporalNode, MasteryLevel
+
+
+class PedagogicalAction(Enum):
+    """Actions the agent can take"""
+    INTRODUCE = "introduce"  # First time showing concept
+    PRACTICE = "practice"    # Reinforce existing concept
+    REVIEW = "review"        # Remediate forgotten concept
+    TEST = "test"            # Assess mastery
+    WAIT = "wait"            # No action needed
+
+
+class CurriculumPolicy:
+    """
+    Decides WHAT to teach and WHEN.
+    Core of proactive behavior.
+    """
+    
+    def __init__(self, review_threshold: float = 0.4, mastery_threshold: float = 0.8):
+        self.review_threshold = review_threshold
+        self.mastery_threshold = mastery_threshold
+    
+    def decide_next_action(
+        self, 
+        knowledge_graph: dict[str, TemporalNode]
+    ) -> Tuple[PedagogicalAction, Optional[TemporalNode]]:
+        """
+        Proactive decision logic.
+        Returns: (action, target_node)
+        """
+        
+        # Priority 1: Review forgotten concepts (urgent)
+        for node in knowledge_graph.values():
+            if node.mastery == MasteryLevel.NEEDS_REVIEW:
+                return PedagogicalAction.REVIEW, node
+        
+        # Priority 2: Practice concepts being learned
+        practicing_nodes = [
+            n for n in knowledge_graph.values() 
+            if n.mastery == MasteryLevel.PRACTICING
+        ]
+        if practicing_nodes:
+            # Focus on weakest concept
+            weakest = min(practicing_nodes, key=lambda n: n.confidence)
+            return PedagogicalAction.PRACTICE, weakest
+        
+        # Priority 3: Introduce new concepts (if prerequisites met)
+        for node in knowledge_graph.values():
+            if node.mastery == MasteryLevel.NOT_SEEN:
+                if self._prerequisites_satisfied(node, knowledge_graph):
+                    return PedagogicalAction.INTRODUCE, node
+        
+        # Priority 4: Test mastered concepts periodically
+        mastered = [n for n in knowledge_graph.values() 
+                   if n.mastery == MasteryLevel.MASTERED]
+        if mastered and len(mastered) % 5 == 0:  # Every 5 mastered concepts
+            return PedagogicalAction.TEST, mastered[0]
+        
+        # Nothing to do
+        return PedagogicalAction.WAIT, None
+    
+    def _prerequisites_satisfied(
+        self, 
+        node: TemporalNode, 
+        graph: dict[str, TemporalNode]
+    ) -> bool:
+        """Check if all prerequisites are mastered"""
+        for prereq_id in node.prerequisites:
+            prereq = graph.get(prereq_id)
+            if not prereq:
+                return False
+            if prereq.mastery not in [MasteryLevel.MASTERED, MasteryLevel.PRACTICING]:
+                return False
+        return True

dialograph-0.3.0/src/dialograph/core/__init__.py

@@ -0,0 +1,7 @@
+# dialograph/core/__init__.py
+
+from .node import Node
+from .edge import Edge
+from .graph import Dialograph
+
+__all__ = ["Node", "Edge", "Dialograph"]

dialograph-0.3.0/src/dialograph/core/draw.py

@@ -0,0 +1,7 @@
+from graphviz import Digraph
+
+def trace(root):
+    pass 
+
+def draw_dot():
+    pass