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.
- branchy_chat-0.1.1/PKG-INFO +84 -0
- branchy_chat-0.1.1/README.md +72 -0
- branchy_chat-0.1.1/pyproject.toml +27 -0
- branchy_chat-0.1.1/setup.cfg +4 -0
- branchy_chat-0.1.1/src/branchy/__init__.py +4 -0
- branchy_chat-0.1.1/src/branchy/chat.py +147 -0
- branchy_chat-0.1.1/src/branchy/models.py +13 -0
- branchy_chat-0.1.1/src/branchy/signatures.py +36 -0
- branchy_chat-0.1.1/src/branchy/tree.py +94 -0
- branchy_chat-0.1.1/src/branchy_chat.egg-info/PKG-INFO +84 -0
- branchy_chat-0.1.1/src/branchy_chat.egg-info/SOURCES.txt +12 -0
- branchy_chat-0.1.1/src/branchy_chat.egg-info/dependency_links.txt +1 -0
- branchy_chat-0.1.1/src/branchy_chat.egg-info/requires.txt +2 -0
- branchy_chat-0.1.1/src/branchy_chat.egg-info/top_level.txt +1 -0
|
@@ -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,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 @@
|
|
|
1
|
+
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
branchy
|