branchy-chat 0.1.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Potentially problematic release.


This version of branchy-chat might be problematic. Click here for more details.

@@ -0,0 +1,84 @@
1
+ Metadata-Version: 2.4
2
+ Name: branchy-chat
3
+ Version: 0.1.1
4
+ Summary: Branching conversation trees for AI chat. Store, retrieve, and route conversations with tree-based memory.
5
+ Author-email: Bhasker Raju <saibhaskerraju@outlook.com>
6
+ Maintainer-email: Bhasker Raju <saibhaskerraju@outlook.com>
7
+ Keywords: conversation,tree,chat,llm,branching
8
+ Requires-Python: ~=3.12.0
9
+ Description-Content-Type: text/markdown
10
+ Requires-Dist: dspy==3.0.4
11
+ Requires-Dist: pydantic>=2.12.5
12
+
13
+ # branchy-chat
14
+
15
+ Store conversation messages as a tree structure, retrieve relevant context traces, and let your LLM automatically route new prompts to the right branch.
16
+
17
+ - 🌳 Tree-based conversation memory
18
+ - 🔍 Retrieve relevant conversation traces
19
+ - 🧠 LLM-powered branch routing
20
+ - 📦 Publishable pip package
21
+
22
+ ## Installation
23
+
24
+ ```bash
25
+ pip install branchy-chat
26
+ ```
27
+
28
+ ## Usage
29
+
30
+ ```python
31
+ from branchy import BranchingChat
32
+
33
+ chat = BranchingChat(
34
+ model="openai/gpt-4o-mini",
35
+ api_key="<your-api-key>",
36
+ api_base="http://localhost:4000", # Optional, useful for LiteLLM proxy
37
+ )
38
+
39
+ message_id_1 = chat.add_message("How do I build an index in Postgres?")
40
+ message_id_2 = chat.add_message("What if I need it concurrently?")
41
+
42
+ # Prints and returns the tree as text.
43
+ chat.show_tree()
44
+ ```
45
+
46
+ ### LiteLLM compatibility
47
+
48
+ `BranchingChat` supports LiteLLM-style parameters:
49
+
50
+ - `model`
51
+ - `api_key`
52
+ - `api_base`
53
+
54
+ This means you can point it at a LiteLLM proxy endpoint by setting `api_base`.
55
+
56
+ ## API
57
+
58
+ - `BranchingChat(*, model, api_key=None, api_base=None, **lm_kwargs)`
59
+ : Initialize using LiteLLM-compatible arguments.
60
+ - `BranchingChat.add_message(user_message: str) -> str`
61
+ : Routes a message to the best branch, stores it in the tree, and returns the new `message_id`.
62
+ - `BranchingChat.show_tree(print_output: bool = True) -> str`
63
+ : Renders user messages in an ASCII tree format and prints it by default.
64
+
65
+ ## Release Automation (GitHub Actions)
66
+
67
+ This repository includes two workflows:
68
+
69
+ 1. `.github/workflows/create-release.yml`
70
+ : Manual workflow that validates the version, creates tag `vX.Y.Z`, and publishes a GitHub Release.
71
+ 2. `.github/workflows/publish-pypi.yml`
72
+ : Automatically publishes to PyPI when a GitHub Release is published.
73
+
74
+ One-time setup:
75
+
76
+ 1. Create a PyPI API token in your PyPI account.
77
+ 2. In GitHub, open repository settings and add a secret named `PYPI_API_TOKEN`.
78
+ 3. Run the `Create Release Tag` workflow from Actions with input `version` matching `pyproject.toml`.
79
+
80
+ After release publish, the PyPI workflow will:
81
+
82
+ 1. Build the package.
83
+ 2. Run `twine check`.
84
+ 3. Upload `dist/*` to PyPI.
@@ -0,0 +1,72 @@
1
+ # branchy-chat
2
+
3
+ Store conversation messages as a tree structure, retrieve relevant context traces, and let your LLM automatically route new prompts to the right branch.
4
+
5
+ - 🌳 Tree-based conversation memory
6
+ - 🔍 Retrieve relevant conversation traces
7
+ - 🧠 LLM-powered branch routing
8
+ - 📦 Publishable pip package
9
+
10
+ ## Installation
11
+
12
+ ```bash
13
+ pip install branchy-chat
14
+ ```
15
+
16
+ ## Usage
17
+
18
+ ```python
19
+ from branchy import BranchingChat
20
+
21
+ chat = BranchingChat(
22
+ model="openai/gpt-4o-mini",
23
+ api_key="<your-api-key>",
24
+ api_base="http://localhost:4000", # Optional, useful for LiteLLM proxy
25
+ )
26
+
27
+ message_id_1 = chat.add_message("How do I build an index in Postgres?")
28
+ message_id_2 = chat.add_message("What if I need it concurrently?")
29
+
30
+ # Prints and returns the tree as text.
31
+ chat.show_tree()
32
+ ```
33
+
34
+ ### LiteLLM compatibility
35
+
36
+ `BranchingChat` supports LiteLLM-style parameters:
37
+
38
+ - `model`
39
+ - `api_key`
40
+ - `api_base`
41
+
42
+ This means you can point it at a LiteLLM proxy endpoint by setting `api_base`.
43
+
44
+ ## API
45
+
46
+ - `BranchingChat(*, model, api_key=None, api_base=None, **lm_kwargs)`
47
+ : Initialize using LiteLLM-compatible arguments.
48
+ - `BranchingChat.add_message(user_message: str) -> str`
49
+ : Routes a message to the best branch, stores it in the tree, and returns the new `message_id`.
50
+ - `BranchingChat.show_tree(print_output: bool = True) -> str`
51
+ : Renders user messages in an ASCII tree format and prints it by default.
52
+
53
+ ## Release Automation (GitHub Actions)
54
+
55
+ This repository includes two workflows:
56
+
57
+ 1. `.github/workflows/create-release.yml`
58
+ : Manual workflow that validates the version, creates tag `vX.Y.Z`, and publishes a GitHub Release.
59
+ 2. `.github/workflows/publish-pypi.yml`
60
+ : Automatically publishes to PyPI when a GitHub Release is published.
61
+
62
+ One-time setup:
63
+
64
+ 1. Create a PyPI API token in your PyPI account.
65
+ 2. In GitHub, open repository settings and add a secret named `PYPI_API_TOKEN`.
66
+ 3. Run the `Create Release Tag` workflow from Actions with input `version` matching `pyproject.toml`.
67
+
68
+ After release publish, the PyPI workflow will:
69
+
70
+ 1. Build the package.
71
+ 2. Run `twine check`.
72
+ 3. Upload `dist/*` to PyPI.
@@ -0,0 +1,27 @@
1
+ [build-system]
2
+ requires = ["setuptools>=69", "wheel"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "branchy-chat"
7
+ version = "0.1.1"
8
+ description = "Branching conversation trees for AI chat. Store, retrieve, and route conversations with tree-based memory."
9
+ readme = "README.md"
10
+ requires-python = "~=3.12.0"
11
+ dependencies = [
12
+ "dspy==3.0.4",
13
+ "pydantic>=2.12.5",
14
+ ]
15
+ authors = [
16
+ {name = "Bhasker Raju", email = "saibhaskerraju@outlook.com"}
17
+ ]
18
+ maintainers = [
19
+ {name = "Bhasker Raju", email = "saibhaskerraju@outlook.com"}
20
+ ]
21
+ keywords = ["conversation", "tree", "chat", "llm", "branching"]
22
+
23
+ [tool.setuptools]
24
+ package-dir = {"" = "src"}
25
+
26
+ [tool.setuptools.packages.find]
27
+ where = ["src"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,4 @@
1
+ from .chat import BranchingChat
2
+ from .tree import ConversationTree
3
+
4
+ __all__ = ["BranchingChat", "ConversationTree"]
@@ -0,0 +1,147 @@
1
+ from __future__ import annotations
2
+
3
+ from typing import Any, Optional
4
+
5
+ import dspy
6
+
7
+ from .signatures import ConnectionDecision, ResponseGenerator, SingleTraceRelevance
8
+ from .tree import ConversationTree
9
+
10
+
11
+ class BranchingChat:
12
+ """Branch-aware chat manager that routes messages into a conversation tree."""
13
+
14
+ def __init__(
15
+ self,
16
+ *,
17
+ model: str,
18
+ api_key: Optional[str] = None,
19
+ api_base: Optional[str] = None,
20
+ **lm_kwargs: Any,
21
+ ) -> None:
22
+ """Create a chat instance.
23
+
24
+ Initializes a DSPy LM from LiteLLM-compatible parameters.
25
+ """
26
+
27
+ llm = dspy.LM(
28
+ model=model,
29
+ api_key=api_key,
30
+ api_base=api_base,
31
+ **lm_kwargs,
32
+ )
33
+
34
+ dspy.settings.configure(lm=llm)
35
+ self.tree = ConversationTree()
36
+ self.llm = llm
37
+
38
+ self.evaluator = dspy.ChainOfThought(SingleTraceRelevance)
39
+ self.decider = dspy.ChainOfThought(ConnectionDecision)
40
+ self.responder = dspy.ChainOfThought(ResponseGenerator)
41
+
42
+ def add_message(self, user_message: str) -> str:
43
+ """Add a user message, route it in the tree, and return the new message id."""
44
+
45
+ best_match = self._find_best_trace(user_message)
46
+ decision = self._decide_action(user_message, best_match)
47
+ response = self._generate_response(user_message, decision)
48
+
49
+ message_id = self.tree.add_message(
50
+ user=user_message,
51
+ assistant=response,
52
+ parent_message_id=decision["target_message_id"],
53
+ )
54
+ return message_id
55
+
56
+ def show_tree(self, print_output: bool = True) -> str:
57
+ """Render the current user-message tree and optionally print it."""
58
+
59
+ tree_output = self.tree.render_tree()
60
+ if print_output:
61
+ print(tree_output)
62
+ return tree_output
63
+
64
+ def _find_best_trace(self, user_message: str) -> Optional[dict[str, Any]]:
65
+ all_traces = self.tree.get_all_traces(max_window=3)
66
+ if not all_traces:
67
+ return None
68
+
69
+ best_score = -1.0
70
+ best_trace: Optional[dict[str, Any]] = None
71
+ best_reasoning = ""
72
+
73
+ for trace in all_traces:
74
+ result = self.evaluator(
75
+ user_message=user_message,
76
+ conversation_trace=trace["formatted_text"],
77
+ )
78
+
79
+ try:
80
+ score = float(result.relevance_score)
81
+ score = max(0.0, min(1.0, score))
82
+ except (TypeError, ValueError):
83
+ score = 0.0
84
+
85
+ if score > best_score:
86
+ best_score = score
87
+ best_trace = trace
88
+ best_reasoning = result.reasoning
89
+ elif score == best_score and best_trace:
90
+ if trace["window_size"] > best_trace["window_size"]:
91
+ best_trace = trace
92
+ best_reasoning = result.reasoning
93
+
94
+ return {"trace": best_trace, "score": best_score, "reasoning": best_reasoning}
95
+
96
+ def _decide_action(
97
+ self,
98
+ user_message: str,
99
+ best_match: Optional[dict[str, Any]],
100
+ ) -> dict[str, Any]:
101
+ if best_match is None:
102
+ return {
103
+ "action": "NEW_ROOT",
104
+ "explanation": "No existing conversations, starting new root",
105
+ "target_message_id": None,
106
+ }
107
+
108
+ decision_result = self.decider(
109
+ user_message=user_message,
110
+ best_trace_score=str(best_match["score"]),
111
+ best_trace_text=best_match["trace"]["formatted_text"],
112
+ )
113
+
114
+ action = decision_result.action.strip().upper()
115
+ if action == "ATTACH":
116
+ return {
117
+ "action": "ATTACH",
118
+ "explanation": decision_result.explanation,
119
+ "target_message_id": best_match["trace"]["end_message_id"],
120
+ }
121
+ if action == "NEW_BRANCH":
122
+ root_of_trace = best_match["trace"]["messages"][0]
123
+ return {
124
+ "action": "NEW_BRANCH",
125
+ "explanation": decision_result.explanation,
126
+ "target_message_id": root_of_trace.message_id,
127
+ }
128
+
129
+ return {
130
+ "action": "NEW_ROOT",
131
+ "explanation": decision_result.explanation,
132
+ "target_message_id": None,
133
+ }
134
+
135
+ def _generate_response(self, user_message: str, decision: dict[str, Any]) -> str:
136
+ if decision["action"] in ("ATTACH", "NEW_BRANCH") and decision["target_message_id"]:
137
+ path = self.tree.get_path_to_root(decision["target_message_id"])
138
+ context_lines = []
139
+ for message in path:
140
+ context_lines.append(f"User: {message.user}")
141
+ context_lines.append(f"Assistant: {message.assistant}")
142
+ context = "\n".join(context_lines)
143
+ else:
144
+ context = "Starting a completely new conversation"
145
+
146
+ result = self.responder(context=context, user_message=user_message)
147
+ return result.response
@@ -0,0 +1,13 @@
1
+ from __future__ import annotations
2
+
3
+ from typing import Optional
4
+
5
+ from pydantic import BaseModel, Field
6
+
7
+
8
+ class MessageNode(BaseModel):
9
+ message_id: str
10
+ user: str
11
+ assistant: str
12
+ parent_message_id: Optional[str]
13
+ child_message_ids: list[str] = Field(default_factory=list)
@@ -0,0 +1,36 @@
1
+ from __future__ import annotations
2
+
3
+ import dspy
4
+
5
+
6
+ class SingleTraceRelevance(dspy.Signature):
7
+ """Evaluate how relevant a conversation trace is for a new user message."""
8
+
9
+ user_message = dspy.InputField()
10
+ conversation_trace = dspy.InputField()
11
+
12
+ relevance_score = dspy.OutputField(desc="Float between 0.0 and 1.0")
13
+ reasoning = dspy.OutputField(desc="Brief explanation")
14
+
15
+
16
+ class ConnectionDecision(dspy.Signature):
17
+ """Decide where to attach the user's message in the conversation tree."""
18
+
19
+ user_message = dspy.InputField()
20
+ best_trace_score = dspy.InputField(
21
+ desc="Relevance score of best matching trace (0-1)")
22
+ best_trace_text = dspy.InputField(
23
+ desc="The conversation trace with highest score")
24
+
25
+ action = dspy.OutputField(
26
+ desc="One of: 'ATTACH', 'NEW_BRANCH', 'NEW_ROOT'")
27
+ explanation = dspy.OutputField(desc="Why you chose this action")
28
+
29
+
30
+ class ResponseGenerator(dspy.Signature):
31
+ """Generate a helpful response using the selected conversation context."""
32
+
33
+ context = dspy.InputField(desc="Previous conversation history")
34
+ user_message = dspy.InputField()
35
+
36
+ response = dspy.OutputField(desc="Helpful, natural response")
@@ -0,0 +1,94 @@
1
+ from __future__ import annotations
2
+
3
+ from typing import Any, Optional
4
+ import uuid
5
+
6
+ from .models import MessageNode
7
+
8
+
9
+ class ConversationTree:
10
+ def __init__(self) -> None:
11
+ self.messages: dict[str, MessageNode] = {}
12
+
13
+ def add_message(self, user: str, assistant: str, parent_message_id: Optional[str] = None) -> str:
14
+ message_id = str(uuid.uuid4())[:6]
15
+ message = MessageNode(
16
+ message_id=message_id,
17
+ user=user,
18
+ assistant=assistant,
19
+ parent_message_id=parent_message_id,
20
+ )
21
+ self.messages[message_id] = message
22
+
23
+ if parent_message_id and parent_message_id in self.messages:
24
+ self.messages[parent_message_id].child_message_ids.append(
25
+ message_id)
26
+
27
+ return message_id
28
+
29
+ def get_path_to_root(self, message_id: str) -> list[MessageNode]:
30
+ path: list[MessageNode] = []
31
+ current_id = message_id
32
+
33
+ while current_id and current_id in self.messages:
34
+ message = self.messages[current_id]
35
+ path.insert(0, message)
36
+ current_id = message.parent_message_id
37
+
38
+ return path
39
+
40
+ def get_all_traces(self, max_window: int = 3) -> list[dict[str, Any]]:
41
+ traces: list[dict[str, Any]] = []
42
+
43
+ for message_id in self.messages:
44
+ full_path = self.get_path_to_root(message_id)
45
+
46
+ for window_size in range(1, min(len(full_path), max_window) + 1):
47
+ window = full_path[-window_size:]
48
+
49
+ trace_lines = []
50
+ for message in window:
51
+ trace_lines.append(f"User: {message.user}")
52
+ trace_lines.append(f"Assistant: {message.assistant}")
53
+ trace_lines.append("")
54
+
55
+ traces.append(
56
+ {
57
+ "trace_id": f"{message_id}_w{window_size}",
58
+ "end_message_id": message_id,
59
+ "window_size": window_size,
60
+ "messages": window,
61
+ "formatted_text": "\n".join(trace_lines),
62
+ }
63
+ )
64
+
65
+ return traces
66
+
67
+ def get_root_messages(self) -> list[MessageNode]:
68
+ return [message for message in self.messages.values() if message.parent_message_id is None]
69
+
70
+ def render_tree(self) -> str:
71
+ if not self.messages:
72
+ return "Empty tree"
73
+
74
+ lines = []
75
+ roots = self.get_root_messages()
76
+
77
+ for root_message in roots:
78
+ lines.extend(self._render_message(root_message, "", is_last=True))
79
+
80
+ return "\n".join(lines)
81
+
82
+ def _render_message(self, message: MessageNode, prefix: str, is_last: bool) -> list[str]:
83
+ branch = "└── " if is_last else "├── "
84
+ header = f"{prefix}{branch}[{message.message_id}] User: {message.user}"
85
+ lines = [header]
86
+
87
+ next_prefix = prefix + (" " if is_last else "│ ")
88
+ for index, child_id in enumerate(message.child_message_ids):
89
+ child = self.messages[child_id]
90
+ child_is_last = index == len(message.child_message_ids) - 1
91
+ lines.extend(self._render_message(
92
+ child, next_prefix, child_is_last))
93
+
94
+ return lines
@@ -0,0 +1,84 @@
1
+ Metadata-Version: 2.4
2
+ Name: branchy-chat
3
+ Version: 0.1.1
4
+ Summary: Branching conversation trees for AI chat. Store, retrieve, and route conversations with tree-based memory.
5
+ Author-email: Bhasker Raju <saibhaskerraju@outlook.com>
6
+ Maintainer-email: Bhasker Raju <saibhaskerraju@outlook.com>
7
+ Keywords: conversation,tree,chat,llm,branching
8
+ Requires-Python: ~=3.12.0
9
+ Description-Content-Type: text/markdown
10
+ Requires-Dist: dspy==3.0.4
11
+ Requires-Dist: pydantic>=2.12.5
12
+
13
+ # branchy-chat
14
+
15
+ Store conversation messages as a tree structure, retrieve relevant context traces, and let your LLM automatically route new prompts to the right branch.
16
+
17
+ - 🌳 Tree-based conversation memory
18
+ - 🔍 Retrieve relevant conversation traces
19
+ - 🧠 LLM-powered branch routing
20
+ - 📦 Publishable pip package
21
+
22
+ ## Installation
23
+
24
+ ```bash
25
+ pip install branchy-chat
26
+ ```
27
+
28
+ ## Usage
29
+
30
+ ```python
31
+ from branchy import BranchingChat
32
+
33
+ chat = BranchingChat(
34
+ model="openai/gpt-4o-mini",
35
+ api_key="<your-api-key>",
36
+ api_base="http://localhost:4000", # Optional, useful for LiteLLM proxy
37
+ )
38
+
39
+ message_id_1 = chat.add_message("How do I build an index in Postgres?")
40
+ message_id_2 = chat.add_message("What if I need it concurrently?")
41
+
42
+ # Prints and returns the tree as text.
43
+ chat.show_tree()
44
+ ```
45
+
46
+ ### LiteLLM compatibility
47
+
48
+ `BranchingChat` supports LiteLLM-style parameters:
49
+
50
+ - `model`
51
+ - `api_key`
52
+ - `api_base`
53
+
54
+ This means you can point it at a LiteLLM proxy endpoint by setting `api_base`.
55
+
56
+ ## API
57
+
58
+ - `BranchingChat(*, model, api_key=None, api_base=None, **lm_kwargs)`
59
+ : Initialize using LiteLLM-compatible arguments.
60
+ - `BranchingChat.add_message(user_message: str) -> str`
61
+ : Routes a message to the best branch, stores it in the tree, and returns the new `message_id`.
62
+ - `BranchingChat.show_tree(print_output: bool = True) -> str`
63
+ : Renders user messages in an ASCII tree format and prints it by default.
64
+
65
+ ## Release Automation (GitHub Actions)
66
+
67
+ This repository includes two workflows:
68
+
69
+ 1. `.github/workflows/create-release.yml`
70
+ : Manual workflow that validates the version, creates tag `vX.Y.Z`, and publishes a GitHub Release.
71
+ 2. `.github/workflows/publish-pypi.yml`
72
+ : Automatically publishes to PyPI when a GitHub Release is published.
73
+
74
+ One-time setup:
75
+
76
+ 1. Create a PyPI API token in your PyPI account.
77
+ 2. In GitHub, open repository settings and add a secret named `PYPI_API_TOKEN`.
78
+ 3. Run the `Create Release Tag` workflow from Actions with input `version` matching `pyproject.toml`.
79
+
80
+ After release publish, the PyPI workflow will:
81
+
82
+ 1. Build the package.
83
+ 2. Run `twine check`.
84
+ 3. Upload `dist/*` to PyPI.
@@ -0,0 +1,12 @@
1
+ README.md
2
+ pyproject.toml
3
+ src/branchy/__init__.py
4
+ src/branchy/chat.py
5
+ src/branchy/models.py
6
+ src/branchy/signatures.py
7
+ src/branchy/tree.py
8
+ src/branchy_chat.egg-info/PKG-INFO
9
+ src/branchy_chat.egg-info/SOURCES.txt
10
+ src/branchy_chat.egg-info/dependency_links.txt
11
+ src/branchy_chat.egg-info/requires.txt
12
+ src/branchy_chat.egg-info/top_level.txt
@@ -0,0 +1,2 @@
1
+ dspy==3.0.4
2
+ pydantic>=2.12.5