bot-knows 0.1.0__py3-none-any.whl

bot_knows/utils/hashing.py

@@ -0,0 +1,126 @@
+"""Hashing utilities for bot_knows.
+
+This module provides deterministic hash functions for generating
+stable identifiers for chats, messages, topics, and evidence.
+"""
+
+import hashlib
+from typing import Any
+
+__all__ = [
+    "generate_chat_id",
+    "generate_evidence_id",
+    "generate_message_id",
+    "generate_topic_id",
+    "hash_text",
+]
+
+
+def hash_text(text: str) -> str:
+    """Generate SHA256 hash of text.
+
+    Args:
+        text: Input text to hash
+
+    Returns:
+        Hexadecimal SHA256 hash string
+    """
+    return hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+
+def generate_chat_id(title: str, source: str, timestamp: int) -> str:
+    """Generate deterministic chat ID.
+
+    The chat ID is a SHA256 hash of: title + source + timestamp.
+    This ensures the same chat imported multiple times gets the same ID.
+
+    Args:
+        title: Chat title
+        source: Import source (e.g., "chatgpt", "claude")
+        timestamp: Chat creation timestamp (epoch seconds)
+
+    Returns:
+        Hexadecimal SHA256 hash string
+    """
+    combined = f"{title}|{source}|{timestamp}"
+    return hash_text(combined)
+
+
+def generate_message_id(
+    chat_id: str,
+    user_content: str,
+    assistant_content: str,
+    timestamp: int,
+) -> str:
+    """Generate deterministic message ID.
+
+    The message ID is based on chat_id + content + timestamp to ensure
+    uniqueness within a chat while being deterministic.
+
+    Args:
+        chat_id: Parent chat ID
+        user_content: User message content
+        assistant_content: Assistant response content
+        timestamp: Message timestamp (epoch seconds)
+
+    Returns:
+        Hexadecimal SHA256 hash string
+    """
+    combined = f"{chat_id}|{user_content}|{assistant_content}|{timestamp}"
+    return hash_text(combined)
+
+
+def generate_topic_id(canonical_name: str, source_message_id: str) -> str:
+    """Generate deterministic topic ID.
+
+    The topic ID combines the canonical name with the first message
+    that introduced it, ensuring uniqueness.
+
+    Args:
+        canonical_name: Canonical topic name
+        source_message_id: ID of the message that first introduced this topic
+
+    Returns:
+        Hexadecimal SHA256 hash string
+    """
+    combined = f"topic|{canonical_name}|{source_message_id}"
+    return hash_text(combined)
+
+
+def generate_evidence_id(
+    topic_id: str,
+    extracted_name: str,
+    source_message_id: str,
+    timestamp: int,
+) -> str:
+    """Generate deterministic evidence ID.
+
+    Evidence IDs are unique per extraction event.
+
+    Args:
+        topic_id: Parent topic ID
+        extracted_name: Raw extracted topic name
+        source_message_id: Source message ID
+        timestamp: Extraction timestamp (epoch seconds)
+
+    Returns:
+        Hexadecimal SHA256 hash string
+    """
+    combined = f"evidence|{topic_id}|{extracted_name}|{source_message_id}|{timestamp}"
+    return hash_text(combined)
+
+
+def stable_hash(*args: Any) -> str:
+    """Generate a stable hash from multiple arguments.
+
+    Converts all arguments to strings and joins them with pipe separator.
+    Useful for creating composite keys.
+
+    Args:
+        *args: Values to include in the hash
+
+    Returns:
+        Hexadecimal SHA256 hash string
+    """
+    combined = "|".join(str(arg) for arg in args)
+    return hash_text(combined)

bot_knows-0.1.0.dist-info/METADATA

@@ -0,0 +1,294 @@
+Metadata-Version: 2.4
+Name: bot-knows
+Version: 0.1.0
+Summary: Framework-agnostic Python library for graph-backed personal knowledge bases from chat data
+Project-URL: Homepage, https://github.com/Snezhana/bot-knows
+Project-URL: Documentation, https://github.com/Snezhana/bot-knows#readme
+Project-URL: Repository, https://github.com/Snezhana/bot-knows
+Project-URL: Issues, https://github.com/Snezhana/bot-knows/issues
+Author-email: Your Name <your@email.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: chat,embedding,graph,knowledge-base,memory,nlp,recall
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: anthropic<1.0,>=0.42
+Requires-Dist: anyio<5.0,>=4.7
+Requires-Dist: motor<4.0,>=3.6
+Requires-Dist: neo4j<6.0,>=5.27
+Requires-Dist: numpy<3.0,>=2.2
+Requires-Dist: openai<2.0,>=1.59
+Requires-Dist: pydantic-settings<3.0,>=2.6
+Requires-Dist: pydantic<3.0,>=2.10
+Requires-Dist: redis<6.0,>=5.2
+Requires-Dist: structlog<26.0,>=25.1
+Requires-Dist: taskiq-redis<2.0,>=1.0
+Requires-Dist: taskiq<1.0,>=0.11
+Provides-Extra: dev
+Requires-Dist: hypothesis<7.0,>=6.100; extra == 'dev'
+Requires-Dist: mongomock-motor>=0.0.32; extra == 'dev'
+Requires-Dist: mypy<2.0,>=1.14; extra == 'dev'
+Requires-Dist: pre-commit<5.0,>=4.0; extra == 'dev'
+Requires-Dist: pytest-asyncio<1.0,>=0.25; extra == 'dev'
+Requires-Dist: pytest-cov<7.0,>=6.0; extra == 'dev'
+Requires-Dist: pytest<9.0,>=8.3; extra == 'dev'
+Requires-Dist: ruff<1.0,>=0.9; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# bot-knows
+
+A framework-agnostic Python library for building graph-backed personal knowledge bases from chat data.
+
+## Features
+
+- **Multi-source Chat Ingestion**: Import chats from ChatGPT, Claude, and custom JSON formats
+- **Semantic Topic Extraction**: LLM-powered topic extraction with confidence scores
+- **Intelligent Deduplication**: Embedding-based semantic deduplication with configurable thresholds
+- **Graph-backed Knowledge Base**: Neo4j-powered relationship graph for topics and messages
+- **Evidence-weighted Recall**: Spaced repetition-inspired recall system with decay and reinforcement
+- **Pluggable Infrastructure**: Bring your own storage, graph database, or LLM provider
+
+## Requirements
+
+- Python >= 3.13
+- MongoDB (storage) - or custom storage implementation
+- Neo4j (graph database) - or custom graph implementation
+- Redis (optional, for caching)
+- OpenAI or Anthropic API key (for LLM features) - or custom LLM implementation
+
+## Installation
+
+```bash
+pip install bot-knows
+```
+
+Or with uv:
+
+```bash
+uv add bot-knows
+```
+
+## Quick Start
+
+The `BotKnows` class is the main orchestrator that accepts implementation classes for storage, graph database, and LLM providers. Configuration is automatically loaded from environment variables.
+
+### Using Built-in Infrastructure
+
+```python
+from bot_knows import (
+    BotKnows,
+    MongoStorageRepository,
+    Neo4jGraphRepository,
+    OpenAIProvider,
+    ChatGPTAdapter,
+)
+
+async def main():
+    # Config is loaded from .env automatically
+    async with BotKnows(
+        storage_class=MongoStorageRepository,
+        graphdb_class=Neo4jGraphRepository,
+        llm_class=OpenAIProvider,
+    ) as bk:
+        # Import ChatGPT conversations
+        result = await bk.insert_chats("conversations.json", ChatGPTAdapter)
+        print(f"Imported {result.chats_new} chats, {result.topics_created} topics")
+
+        # Query the knowledge base
+        topics = await bk.get_chat_topics(chat_id)
+        due_topics = await bk.get_due_topics(threshold=0.3)
+```
+
+### Available Implementations
+
+**Storage:**
+- `MongoStorageRepository` - MongoDB-based storage
+
+**Graph Database:**
+- `Neo4jGraphRepository` - Neo4j graph database
+
+**LLM Providers:**
+- `OpenAIProvider` - OpenAI API (GPT models + embeddings)
+- `AnthropicProvider` - Anthropic API (Claude models)
+
+**Import Adapters:**
+- `ChatGPTAdapter` - ChatGPT export format
+- `ClaudeAdapter` - Claude export format
+- `GenericJSONAdapter` - Custom JSON format
+
+
+## Custom Implementations
+
+You can provide your own implementations by implementing the required interfaces. Set `config_class = None` on your class and pass configuration via the `*_custom_config` parameters.
+
+### Interfaces
+
+- `StorageInterface` - Persistent storage for chats, messages, topics, evidence, and recall state
+- `GraphServiceInterface` - Graph database operations for the knowledge graph
+- `LLMInterface` - LLM interactions for classification and topic extraction
+- `EmbeddingServiceInterface` - Text embedding generation
+
+### Example: Custom Storage Implementation
+
+```python
+from bot_knows import BotKnows, StorageInterface, Neo4jGraphRepository, OpenAIProvider
+
+class MyCustomStorage:
+    """Custom storage implementation."""
+
+    config_class = None  # Signals custom config
+
+    @classmethod
+    async def from_dict(cls, config: dict) -> "MyCustomStorage":
+        """Factory method for custom config."""
+        return cls(connection_string=config["connection_string"])
+
+    def __init__(self, connection_string: str):
+        self.conn = connection_string
+
+    # Implement all StorageInterface methods...
+    async def save_chat(self, chat): ...
+    async def get_chat(self, chat_id): ...
+    # ... etc
+
+async with BotKnows(
+    storage_class=MyCustomStorage,
+    graphdb_class=Neo4jGraphRepository,
+    llm_class=OpenAIProvider,
+    storage_custom_config={"connection_string": "postgresql://..."},
+) as bk:
+    result = await bk.insert_chats("data.json", ChatGPTAdapter)
+```
+
+### Example: Custom LLM Provider
+
+```python
+from bot_knows import BotKnows, LLMInterface, MongoStorageRepository, Neo4jGraphRepository
+
+class MyLLMProvider:
+    """Custom LLM provider (e.g., local model, different API)."""
+
+    config_class = None
+
+    @classmethod
+    async def from_dict(cls, config: dict) -> "MyLLMProvider":
+        return cls(api_url=config["api_url"], model=config["model"])
+
+    def __init__(self, api_url: str, model: str):
+        self.api_url = api_url
+        self.model = model
+
+    # Implement LLMInterface methods
+    async def classify_chat(self, first_pair, last_pair): ...
+    async def extract_topics(self, user_content, assistant_content): ...
+    async def normalize_topic_name(self, name): ...
+
+    # Implement EmbeddingServiceInterface if used as embedding provider
+    async def embed(self, texts): ...
+
+async with BotKnows(
+    storage_class=MongoStorageRepository,
+    graphdb_class=Neo4jGraphRepository,
+    llm_class=MyLLMProvider,
+    llm_custom_config={"api_url": "http://localhost:8000", "model": "llama3"},
+) as bk:
+    result = await bk.insert_chats("data.json", ChatGPTAdapter)
+```
+
+## Configuration
+
+Configuration is loaded from environment variables. See `.env.example` for all available options.
+
+Key environment variables:
+- `MONGODB_URI` - MongoDB connection string
+- `NEO4J_URI`, `NEO4J_USER`, `NEO4J_PASSWORD` - Neo4j connection
+- `OPENAI_API_KEY` - OpenAI API key
+- `ANTHROPIC_API_KEY` - Anthropic API key
+- `DEDUP_HIGH_THRESHOLD`, `DEDUP_LOW_THRESHOLD` - Deduplication thresholds
+
+## Architecture
+
+```
+Input Sources (ChatGPT, Claude, Custom JSON)
+        ↓
+Import Adapters (normalize to ChatIngest)
+        ↓
+Domain Processing
+  ├── Chat identity resolution
+  ├── One-time Chat classification
+  ├── Message creation & ordering
+        ↓
+Topic Extraction
+  ├── LLM-based extraction
+  ├── Semantic deduplication
+  ├── Evidence append
+        ↓
+Graph Updates (Neo4j)
+```
+
+## Retrieval API
+
+```python
+async with BotKnows(...) as bk:
+    # Get messages for a chat
+    messages = await bk.get_messages_for_chat(chat_id)
+
+    # Get topics for a chat
+    topic_ids = await bk.get_chat_topics(chat_id)
+
+    # Get related topics
+    related = await bk.get_related_topics(topic_id, limit=10)
+
+    # Get topic evidence
+    evidence = await bk.get_topic_evidence(topic_id)
+
+    # Spaced repetition recall
+    recall_state = await bk.get_recall_state(topic_id)
+    due_topics = await bk.get_due_topics(threshold=0.3)
+    all_states = await bk.get_all_recall_states()
+```
+
+## Development
+
+```bash
+# Install with dev dependencies
+uv sync --dev
+
+# Run tests
+uv run pytest
+
+# Type checking
+uv run mypy src/
+
+# Linting
+uv run ruff check src/
+```
+
+## Future Plans
+
+The built-in infrastructure will be extended with additional providers:
+
+- **Storage**: PostgreSQL, SQLite
+- **Graph**: Amazon Neptune, TigerGraph, MemGraph
+- **LLM**: Google Gemini, Ollama, HuggingFace
+
+## Contributing
+
+Contributions are welcome! If you'd like to add a new infrastructure implementation:
+
+1. Implement the appropriate interface (`StorageInterface`, `GraphServiceInterface`, `LLMInterface`, or `EmbeddingServiceInterface`)
+2. Add a `config_class` for environment-based configuration (or set to `None` for custom config)
+3. Implement the `from_config` class method (or `from_dict` if `config_class` is `None`)
+4. Add tests for your implementation
+5. Submit a pull request
+
+## License
+
+MIT

bot_knows-0.1.0.dist-info/RECORD

@@ -0,0 +1,56 @@
+bot_knows/__init__.py,sha256=2YtzVyPMHcfBMRK-l0glSbMtnl97ppdtqVFKwdl_F-4,2246
+bot_knows/config.py,sha256=1BLyyRWxloUCqkIrIWBE7iPyvbnxgoBUj3w901FpmbU,2972
+bot_knows/logging.py,sha256=Hn7t7tw8dMbxzc10QNeJ8l0jllth3TUpA55PiyIbvPU,2715
+bot_knows/orchestrator.py,sha256=5x93HLdCiBlWzC4TAvTeVShG5Op7v75GMCezx3M6VhE,15361
+bot_knows/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+bot_knows/domain/__init__.py,sha256=3GzhgssFbe-_r8bhlQBMG2267JQrSbAAD1YtNrfHxEw,151
+bot_knows/domain/chat.py,sha256=G4ajsoItoiW8usBBqub3r7UUuYoBvYknStVv3PCJO_4,1618
+bot_knows/domain/message.py,sha256=a4betNQ5s-R6ZvUrrVesrCldIYpLTUvJmUn5X5aXF_Y,1793
+bot_knows/domain/relation.py,sha256=z7MAK4Bf6C_MfhmBt2pq3CHWx4HmxgPW24vPD8Hm1o4,1375
+bot_knows/domain/topic.py,sha256=d4Sntbk7fs1B_z6N_qr6zp_8R42KvOrHQm1cGevF1Qc,4367
+bot_knows/domain/topic_evidence.py,sha256=yrDNvNdoW3pfT1k9QGfc-GJ_E4USAIhIGt1f3a2B5UA,1603
+bot_knows/importers/__init__.py,sha256=5QwL3BuxgJHVz6hzTrxLEYxFwvNgywzFSYn9EVbuyoo,291
+bot_knows/importers/base.py,sha256=M2HTVh3L0j5Jjj6gP72yGn1asKX4F9Lq8YJyglSotSA,3048
+bot_knows/importers/chatgpt.py,sha256=YFtAaI8GgaIGPsMXBjvWAcwdUjGY3FjNzDsLEXPxKX0,4666
+bot_knows/importers/claude.py,sha256=X3gjrYXdAuRUD0tCWRAbcXD6jXbX1-0o1LQQGWRN-ew,5475
+bot_knows/importers/generic_json.py,sha256=UTngXdw0KTcUnzSsXINFdDWU86kW5Rh85-MQstaEhyI,8879
+bot_knows/importers/registry.py,sha256=ZZRTcbSkNC1tZuZnKMWspFsdHFIZmkpvzG8JN6tk5P0,3405
+bot_knows/infra/__init__.py,sha256=9vRgOa4HBmNhhYh1sC7SLInN5qZoPf7pXbb_UxdBCyI,166
+bot_knows/infra/llm/__init__.py,sha256=H2EplSurbmpun-jNPznUr-KWm8JaF8fuBmDMLWHT9Uk,234
+bot_knows/infra/llm/anthropic_provider.py,sha256=nOdOCc1jljrA3LZmutuNfAHpiBPlHUxAwnuymmwrY2I,5774
+bot_knows/infra/llm/openai_provider.py,sha256=zBTxtdZPovR6GDPSy6QBWRqJlW2C47nwvhsnuQvniv8,6650
+bot_knows/infra/mongo/__init__.py,sha256=UfYYi8N0gp9pdbzOl7guzI_VYiowZ_IuFjoPokeyciM,125
+bot_knows/infra/mongo/client.py,sha256=hrLGQl5pizTgQAfB8FhLNT3YH8mf3Cjwf70sjIvcubM,4561
+bot_knows/infra/mongo/repositories.py,sha256=jrmY0sBRufcOQB7BF3EIM8sZLr7_h29LMs93osx4a_s,12411
+bot_knows/infra/neo4j/__init__.py,sha256=akgXC0DbbNFSFfsQ2aFewlSs-Wko8vRGFYwmbQiKtkk,123
+bot_knows/infra/neo4j/client.py,sha256=x6CFmAJw_KFSUpL1E7USPpGTKUQdje7OUB0rIlvI_BI,4623
+bot_knows/infra/neo4j/graph_repository.py,sha256=fFLsxMqqBoEheKN4z703SfY4ouUCAdhe4vfDIvelm9c,10936
+bot_knows/infra/redis/__init__.py,sha256=P00gyYoxYYhH8c2ZwWnEginTM0uCjS9Py2KmI2avnIU,207
+bot_knows/infra/redis/cache.py,sha256=ybeMuq_JKGtDn0QoWSQRff5t9pJwzRKQfzfnBUORiGY,4903
+bot_knows/infra/redis/client.py,sha256=HUBXX7DQqmip2UOxloeNJOe1L5ZHXuJkEthu-z3BkSI,5456
+bot_knows/interfaces/__init__.py,sha256=CHsG3hqjxatHR27az6QK7kY4_GmsWc5BiXX-cgDNKJE,572
+bot_knows/interfaces/embedding.py,sha256=KzMupF3lpodBJQ8vbBKzvAHyUbnjLRH79BSTHyq79ss,1364
+bot_knows/interfaces/graph.py,sha256=5YlkOGjHE4aM4Bba-hRwCMATmsXbTQuMq6QkRyR6Xck,4823
+bot_knows/interfaces/llm.py,sha256=XoxkKhEPGdFjp3XcWR20_usT2WU94XRCWpQ-bzo07dk,1802
+bot_knows/interfaces/recall.py,sha256=Z4D-ki1LhY5OVZfayuiW4WP6bcERBfMlXs0yiQICMPY,2485
+bot_knows/interfaces/storage.py,sha256=sueoZfNiurQ-ZyZ-IJ7BrLz8ooO5YOBEnnkA8VGQDs4,5324
+bot_knows/models/__init__.py,sha256=cFlEwzNHm6hBDgH7Jtswgg5U65JfxQLiYxm3-rB5C60,590
+bot_knows/models/chat.py,sha256=_hWXeXuoOR7theOkT0jM5Sf_ff3MbquECPRszOUgjIg,1616
+bot_knows/models/ingest.py,sha256=JO8F_s8W3rLUONqOqHD5HE6FeAqb3-F0PI1BBXkYK-c,2515
+bot_knows/models/message.py,sha256=rAYMchsfv78Pig3qxEI2XXbsQLG1tq9-FT77FE4Flnw,1716
+bot_knows/models/recall.py,sha256=SGdPqSwlmx5ZoG53hv6tzNQsV_NTJsgkuKcY-2E1OkQ,1973
+bot_knows/models/topic.py,sha256=Ma_6ZskccovKkDVQAmlCL5WEO-dcfsmG0ID2Ag6L-rY,3637
+bot_knows/services/__init__.py,sha256=y8tdc3Zjg_tFL62f8manuxIOL2xkNseSh3n9-MLujFA,766
+bot_knows/services/chat_processing.py,sha256=c9K7V6F25gwSdU5fKCsVepPUIjxG4hyXycpfYTSmtIM,5579
+bot_knows/services/dedup_service.py,sha256=6CXcuddHed1maVozllySUt6QV5Q078eqa-KFsaJmdQk,4892
+bot_knows/services/graph_service.py,sha256=kQ8Of0B9p-eTIOTmf66VySlCQI0BmN_tmjFfNfX_hms,6251
+bot_knows/services/message_builder.py,sha256=pH4JrNxh8EMUZySdkBeZMU1kAkYa67IAnOq-SMfowCs,4305
+bot_knows/services/recall_service.py,sha256=3pl3dFHozhhdxHuMK09tpcnUVjkOLQ9_SwDqmRWGaeQ,9261
+bot_knows/services/tasks.py,sha256=zZY1l6pqB_lRC086HxOoMabJQMbs5V7H-6En53FbNN8,3127
+bot_knows/services/topic_extraction.py,sha256=StKW_DJvH3Fz2V4zSLJXkc1Fz1BJiLsE3gHuDLlZSNk,6059
+bot_knows/utils/__init__.py,sha256=nVhLzC1PyrKznRLNwAIzK-ezQbMI9deSH7b2NYWaJpE,414
+bot_knows/utils/hashing.py,sha256=zojSIplC6QrrEdbY7IzxPOzhadGg_JEXLMP2jKBjH6w,3301
+bot_knows-0.1.0.dist-info/METADATA,sha256=VyQCTKQvp_ti7eWbJvIDxrLw8u0Riw4bUCPKdctuZ8Q,9267
+bot_knows-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+bot_knows-0.1.0.dist-info/licenses/LICENSE,sha256=RHOQqM9jQr_WQ9xFYn0V0QCu3w0T4SphrB38cPmKlhQ,1096
+bot_knows-0.1.0.dist-info/RECORD,,

bot_knows-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

bot_knows-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Snezhana Stojanova
+
+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.