limbiq 0.1.0__tar.gz

limbiq-0.1.0/LICENSE

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

limbiq-0.1.0/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: limbiq
+Version: 0.1.0
+Summary: Neurotransmitter-inspired adaptive learning layer for LLMs
+Author-email: Dimuthu <dimuthu@example.com>
+License: MIT
+Project-URL: Homepage, https://github.com/deBilla/limbiq
+Project-URL: Repository, https://github.com/deBilla/limbiq
+Project-URL: Issues, https://github.com/deBilla/limbiq/issues
+Keywords: llm,memory,adaptive-learning,neurotransmitter,context
+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: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: sentence-transformers>=2.2.0
+Requires-Dist: numpy>=1.24.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Dynamic: license-file
+
+# Limbiq
+
+Neurotransmitter-inspired adaptive learning layer for LLMs.
+
+Limbiq makes any LLM appear to learn and adapt across conversations — without touching a single weight. It sits between the user and the LLM, modifying what the model sees through five discrete signal types inspired by human brain chemistry.
+
+```
+User → Limbiq → Modified Context → Any LLM → Response → Limbiq observes → Loop
+```
+
+## Installation
+
+```bash
+pip install limbiq
+```
+
+## Quick Start
+
+```python
+from limbiq import Limbiq
+
+# Initialize
+lq = Limbiq(
+    store_path="./neuro_data",
+    user_id="dimuthu",
+)
+
+# Before sending to LLM — get enriched context
+result = lq.process(
+    message="What's my wife's name?",
+    conversation_history=[
+        {"role": "user", "content": "Hi there"},
+        {"role": "assistant", "content": "Hello! How can I help?"},
+    ],
+)
+
+# Inject result.context into your system prompt
+messages = [
+    {"role": "system", "content": f"You are a helpful assistant.\n\n{result.context}"},
+    {"role": "user", "content": "What's my wife's name?"},
+]
+response = my_llm(messages)  # Any LLM
+
+# After getting response — let Limbiq observe and learn
+lq.observe("What's my wife's name?", response)
+
+# End session — triggers memory compression
+lq.end_session()
+```
+
+## Signals (v0.1)
+
+### Dopamine — "This matters, remember it"
+
+Fires when the user shares personal info, corrects the model, or gives positive feedback. Tagged memories are **always** included in context.
+
+```python
+lq.dopamine("User's wife is named Prabhashi")
+```
+
+### GABA — "Suppress this, let it fade"
+
+Fires when memories are denied, contradicted, or go stale. Suppression is soft — memories can be restored.
+
+```python
+lq.gaba(memory_id="abc123")
+lq.restore_memory("abc123")  # Undo suppression
+```
+
+### Corrections
+
+Combines both signals — stores new info as priority, suppresses the old.
+
+```python
+lq.correct("User works at Bitsmedia, not Google")
+```
+
+## Inspection
+
+```python
+lq.get_stats()              # Memory counts per tier
+lq.get_signal_log()         # Full history of signals fired
+lq.get_priority_memories()  # All dopamine-tagged memories
+lq.get_suppressed()         # All GABA-suppressed memories
+lq.export_state()           # Full JSON export for debugging
+```
+
+## How It Works
+
+- **LLM-agnostic** — works with any LLM (OpenAI, Anthropic, Ollama, llama.cpp, etc.)
+- **Zero weight modification** — all adaptation through context manipulation
+- **SQLite persistence** — memories survive across sessions
+- **Semantic search** — uses sentence-transformers for embedding-based retrieval (falls back to TF-IDF if not installed)
+- **Transparent** — every signal is logged with trigger, timestamp, and effect
+- **Reversible** — suppressed memories can be restored, nothing is permanently destructive
+
+## License
+
+MIT

limbiq-0.1.0/README.md

@@ -0,0 +1,99 @@
+# Limbiq
+
+Neurotransmitter-inspired adaptive learning layer for LLMs.
+
+Limbiq makes any LLM appear to learn and adapt across conversations — without touching a single weight. It sits between the user and the LLM, modifying what the model sees through five discrete signal types inspired by human brain chemistry.
+
+```
+User → Limbiq → Modified Context → Any LLM → Response → Limbiq observes → Loop
+```
+
+## Installation
+
+```bash
+pip install limbiq
+```
+
+## Quick Start
+
+```python
+from limbiq import Limbiq
+
+# Initialize
+lq = Limbiq(
+    store_path="./neuro_data",
+    user_id="dimuthu",
+)
+
+# Before sending to LLM — get enriched context
+result = lq.process(
+    message="What's my wife's name?",
+    conversation_history=[
+        {"role": "user", "content": "Hi there"},
+        {"role": "assistant", "content": "Hello! How can I help?"},
+    ],
+)
+
+# Inject result.context into your system prompt
+messages = [
+    {"role": "system", "content": f"You are a helpful assistant.\n\n{result.context}"},
+    {"role": "user", "content": "What's my wife's name?"},
+]
+response = my_llm(messages)  # Any LLM
+
+# After getting response — let Limbiq observe and learn
+lq.observe("What's my wife's name?", response)
+
+# End session — triggers memory compression
+lq.end_session()
+```
+
+## Signals (v0.1)
+
+### Dopamine — "This matters, remember it"
+
+Fires when the user shares personal info, corrects the model, or gives positive feedback. Tagged memories are **always** included in context.
+
+```python
+lq.dopamine("User's wife is named Prabhashi")
+```
+
+### GABA — "Suppress this, let it fade"
+
+Fires when memories are denied, contradicted, or go stale. Suppression is soft — memories can be restored.
+
+```python
+lq.gaba(memory_id="abc123")
+lq.restore_memory("abc123")  # Undo suppression
+```
+
+### Corrections
+
+Combines both signals — stores new info as priority, suppresses the old.
+
+```python
+lq.correct("User works at Bitsmedia, not Google")
+```
+
+## Inspection
+
+```python
+lq.get_stats()              # Memory counts per tier
+lq.get_signal_log()         # Full history of signals fired
+lq.get_priority_memories()  # All dopamine-tagged memories
+lq.get_suppressed()         # All GABA-suppressed memories
+lq.export_state()           # Full JSON export for debugging
+```
+
+## How It Works
+
+- **LLM-agnostic** — works with any LLM (OpenAI, Anthropic, Ollama, llama.cpp, etc.)
+- **Zero weight modification** — all adaptation through context manipulation
+- **SQLite persistence** — memories survive across sessions
+- **Semantic search** — uses sentence-transformers for embedding-based retrieval (falls back to TF-IDF if not installed)
+- **Transparent** — every signal is logged with trigger, timestamp, and effect
+- **Reversible** — suppressed memories can be restored, nothing is permanently destructive
+
+## License
+
+MIT

limbiq-0.1.0/limbiq/__init__.py

@@ -0,0 +1,120 @@
+"""
+Limbiq -- Neurotransmitter-inspired adaptive learning for LLMs.
+
+Usage:
+    from limbiq import Limbiq
+
+    lq = Limbiq(store_path="./data", user_id="user1")
+    result = lq.process("Hello, my name is Dimuthu")
+    # ... send to LLM with result.context injected ...
+    lq.observe("Hello, my name is Dimuthu", llm_response)
+"""
+
+from limbiq.core import LimbiqCore
+from limbiq.types import (
+    ProcessResult,
+    SignalEvent,
+    Memory,
+    MemoryTier,
+    SignalType,
+    SuppressionReason,
+)
+
+
+class Limbiq:
+    """Main interface for Limbiq."""
+
+    def __init__(
+        self,
+        store_path: str = "./neuro_data",
+        user_id: str = "default",
+        embedding_model: str = "all-MiniLM-L6-v2",
+        llm_fn=None,
+    ):
+        self._core = LimbiqCore(store_path, user_id, embedding_model, llm_fn)
+
+    def process(
+        self, message: str, conversation_history: list[dict] = None
+    ) -> ProcessResult:
+        """Process a user message and return enriched context for the LLM."""
+        return self._core.process(message, conversation_history)
+
+    def observe(
+        self, message: str, response: str, feedback: str = None
+    ) -> list[SignalEvent]:
+        """Observe a completed exchange and fire appropriate signals."""
+        return self._core.observe(message, response, feedback)
+
+    def start_session(self):
+        """Start a new conversation session."""
+        self._core.start_session()
+
+    def end_session(self) -> dict:
+        """End session and run compression/cleanup."""
+        return self._core.end_session()
+
+    # -- Explicit signals --
+
+    def dopamine(self, content: str):
+        """Manually tag a piece of information as high-priority."""
+        embedding = self._core.embeddings.embed(content)
+        self._core.store.store(
+            content=content,
+            tier=MemoryTier.PRIORITY,
+            confidence=1.0,
+            is_priority=True,
+            source="manual_dopamine",
+            metadata={},
+            embedding=embedding,
+        )
+
+    def gaba(self, memory_id: str):
+        """Manually suppress a memory."""
+        self._core.store.suppress(memory_id, SuppressionReason.MANUAL)
+
+    def correct(self, correction: str):
+        """Apply a correction -- combines dopamine (new info) + gaba (old info)."""
+        self.dopamine(correction)
+
+        embedding = self._core.embeddings.embed(correction)
+        related = self._core.store.search(embedding, top_k=5, include_suppressed=False)
+        for m in related:
+            if m.content != correction:
+                self._core.store.suppress(m.id, SuppressionReason.CONTRADICTED)
+
+    # -- Inspection --
+
+    def get_stats(self) -> dict:
+        """Return memory statistics."""
+        return self._core.store.get_stats()
+
+    def get_signal_log(self, limit: int = 50) -> list[SignalEvent]:
+        """Return recent signal events."""
+        return self._core.signal_log.get_recent(limit)
+
+    def get_priority_memories(self) -> list[Memory]:
+        """Return all dopamine-tagged priority memories."""
+        return self._core.store.get_priority_memories()
+
+    def get_suppressed(self) -> list[Memory]:
+        """Return all GABA-suppressed memories."""
+        return self._core.store.get_suppressed()
+
+    def restore_memory(self, memory_id: str):
+        """Undo a GABA suppression."""
+        self._core.store.restore(memory_id)
+
+    def export_state(self) -> dict:
+        """Export full state as JSON for debugging."""
+        return self._core.store.export_all()
+
+
+__all__ = [
+    "Limbiq",
+    "ProcessResult",
+    "SignalEvent",
+    "Memory",
+    "MemoryTier",
+    "SignalType",
+    "SuppressionReason",
+]

limbiq-0.1.0/limbiq/compression/compressor.py

@@ -0,0 +1,76 @@
+"""
+Memory Compressor -- the lossy compression pipeline.
+
+Full conversations -> gists (mid-term) -> abstract facts (long-term)
+"""
+
+
+class MemoryCompressor:
+    def __init__(self, llm_fn=None):
+        self.llm_fn = llm_fn
+
+    def compress_conversation(self, messages: list[dict]) -> list[str]:
+        if self.llm_fn:
+            return self._llm_compress(messages)
+        else:
+            return self._extractive_compress(messages)
+
+    def _llm_compress(self, messages: list[dict]) -> list[str]:
+        conversation_text = "\n".join(
+            f"{'User' if m['role'] == 'user' else 'Assistant'}: {m['content']}"
+            for m in messages
+            if m.get("role") != "system"
+        )
+
+        prompt = (
+            "Extract individual, self-contained facts from this conversation.\n"
+            "Each fact should be on its own line. Each fact should be independently searchable.\n\n"
+            "Rules:\n"
+            "- One fact per line, no bullets or numbering\n"
+            "- Each fact must be understandable without the others\n"
+            "- Include personal details the user shared (name, job, preferences, family)\n"
+            "- Include key topics discussed and conclusions reached\n"
+            "- Skip greetings, filler, and meta-conversation\n"
+            "- If no meaningful facts exist, respond with NONE\n\n"
+            f"Conversation:\n{conversation_text}"
+        )
+
+        result = self.llm_fn(prompt)
+
+        if "NONE" in result.upper():
+            return []
+
+        facts = [f.strip() for f in result.strip().split("\n") if len(f.strip()) > 10]
+        return facts
+
+    def _extractive_compress(self, messages: list[dict]) -> list[str]:
+        """Fallback: extract key sentences from user messages."""
+        personal_indicators = [
+            "my name",
+            "i work",
+            "i'm a",
+            "i live",
+            "i prefer",
+            "my wife",
+            "my husband",
+            "my partner",
+            "i'm from",
+            "i'm based",
+            "i love",
+            "i hate",
+            "my kid",
+            "my email",
+            "my phone",
+        ]
+
+        facts = []
+        for m in messages:
+            if m.get("role") == "user":
+                content = m["content"].strip()
+                for sentence in content.replace("!", ".").replace("?", ".").split("."):
+                    sentence = sentence.strip()
+                    if len(sentence) > 15 and any(
+                        p in sentence.lower() for p in personal_indicators
+                    ):
+                        facts.append(sentence)
+        return facts

limbiq-0.1.0/limbiq/context/builder.py

@@ -0,0 +1,58 @@
+"""
+Context Builder -- assembles the enriched context string.
+
+This is what gets injected into the system prompt.
+"""
+
+from limbiq.types import Memory
+
+
+class ContextBuilder:
+    def __init__(self, max_tokens: int = 1500):
+        self.max_tokens = max_tokens
+
+    def build(
+        self,
+        priority_memories: list[Memory],
+        relevant_memories: list[Memory],
+        suppressed_ids: set[str],
+    ) -> str:
+        sections = []
+
+        if priority_memories:
+            facts = "\n".join(f"  - {m.content}" for m in priority_memories)
+            sections.append(
+                f"[IMPORTANT -- known facts about this user]\n{facts}"
+            )
+
+        if relevant_memories:
+            priority_ids = {m.id for m in priority_memories}
+            filtered = [
+                m
+                for m in relevant_memories
+                if m.id not in priority_ids and m.id not in suppressed_ids
+            ]
+
+            if filtered:
+                items = "\n".join(
+                    f"  - [{m.confidence:.0%} confidence] {m.content}"
+                    for m in filtered
+                )
+                sections.append(
+                    f"[Relevant memories from previous conversations]\n{items}"
+                )
+
+        if not sections:
+            return ""
+
+        context = "\n\n".join(sections)
+
+        return (
+            "<memory_context>\n"
+            "The following is stored information from previous interactions with this user.\n"
+            "Use it naturally when relevant. If the user asks about something listed here,\n"
+            "reference it confidently. If something is NOT listed here, say you don't know\n"
+            "rather than guessing.\n\n"
+            f"{context}\n"
+            "</memory_context>"
+        )

limbiq-0.1.0/limbiq/core.py

@@ -0,0 +1,152 @@
+"""
+Limbiq Core -- the main orchestrator.
+
+Coordinates detection, signals, storage, retrieval, and context building.
+"""
+
+import uuid
+
+from limbiq.types import (
+    ProcessResult,
+    SignalEvent,
+    SignalType,
+    MemoryTier,
+    SuppressionReason,
+)
+from limbiq.store.memory_store import MemoryStore
+from limbiq.store.embeddings import EmbeddingEngine
+from limbiq.store.signal_log import SignalLog
+from limbiq.context.builder import ContextBuilder
+from limbiq.compression.compressor import MemoryCompressor
+from limbiq.signals.dopamine import DopamineSignal
+from limbiq.signals.gaba import GABASignal
+
+
+class LimbiqCore:
+    def __init__(
+        self,
+        store_path: str,
+        user_id: str,
+        embedding_model: str,
+        llm_fn=None,
+    ):
+        self.store = MemoryStore(store_path, user_id)
+        self.embeddings = EmbeddingEngine(embedding_model)
+        self.compressor = MemoryCompressor(llm_fn)
+        self.context_builder = ContextBuilder()
+        self.signal_log = SignalLog(self.store.db)
+
+        self.signals = [
+            DopamineSignal(),
+            GABASignal(),
+        ]
+
+        self._current_session_id = None
+        self._conversation_buffer: list[dict] = []
+
+    def process(self, message: str, conversation_history: list[dict] = None) -> ProcessResult:
+        query_embedding = self.embeddings.embed(message)
+
+        relevant = self.store.search(
+            query_embedding, top_k=10, include_suppressed=False
+        )
+
+        priority = self.store.get_priority_memories()
+
+        suppressed_ids = {m.id for m in self.store.get_suppressed()}
+
+        for m in relevant:
+            self.store.increment_access(m.id)
+
+        context = self.context_builder.build(priority, relevant, suppressed_ids)
+
+        return ProcessResult(
+            context=context,
+            signals_fired=[],
+            memories_retrieved=len(relevant),
+            priority_count=len(priority),
+            suppressed_count=len(suppressed_ids),
+        )
+
+    def observe(
+        self, message: str, response: str, feedback: str = None
+    ) -> list[SignalEvent]:
+        events = []
+
+        self._conversation_buffer.append({"role": "user", "content": message})
+        self._conversation_buffer.append({"role": "assistant", "content": response})
+
+        existing_memories = self.store.search(
+            self.embeddings.embed(message), top_k=5
+        )
+
+        for signal in self.signals:
+            detected = signal.detect(
+                message=message,
+                response=response,
+                feedback=feedback,
+                memories=existing_memories,
+            )
+            for event in detected:
+                signal.apply(event, self.store, self.embeddings)
+                self.signal_log.log(event)
+                events.append(event)
+
+        if len(message.strip()) > 20:
+            embedding = self.embeddings.embed(message)
+            self.store.store(
+                content=f"User said: {message}",
+                tier=MemoryTier.SHORT,
+                confidence=0.8,
+                is_priority=False,
+                source="conversation",
+                metadata={},
+                embedding=embedding,
+            )
+
+        return events
+
+    def end_session(self) -> dict:
+        results = {"compressed": 0, "aged": 0, "suppressed": 0, "deleted": 0}
+
+        if self._conversation_buffer:
+            facts = self.compressor.compress_conversation(self._conversation_buffer)
+            for fact in facts:
+                embedding = self.embeddings.embed(fact)
+                self.store.store(
+                    content=fact,
+                    tier=MemoryTier.MID,
+                    confidence=0.7,
+                    is_priority=False,
+                    source="compression",
+                    metadata={"source_turns": len(self._conversation_buffer)},
+                    embedding=embedding,
+                )
+                results["compressed"] += 1
+
+            self.store.store_conversation(
+                self._conversation_buffer, self._current_session_id
+            )
+            self._conversation_buffer = []
+
+        self.store.age_all()
+
+        stale = self.store.get_stale(min_sessions=10)
+        for m in stale:
+            gaba_event = SignalEvent(
+                signal_type=SignalType.GABA,
+                trigger="never_accessed",
+                details={"memory_id": m.id, "sessions_old": m.session_count},
+                memory_ids_affected=[m.id],
+            )
+            self.store.suppress(m.id, SuppressionReason.NEVER_ACCESSED)
+            self.signal_log.log(gaba_event)
+            results["suppressed"] += 1
+
+        results["deleted"] = self.store.delete_old_suppressed(min_sessions=30)
+
+        return results
+
+    def start_session(self):
+        self._current_session_id = str(uuid.uuid4())[:8]
+        self._conversation_buffer = []

limbiq-0.1.0/limbiq/detection/detector.py

@@ -0,0 +1,28 @@
+"""Main signal detector -- analyzes input and determines which signals to fire."""
+
+from limbiq.types import Memory, SignalEvent
+from limbiq.signals.base import BaseSignal
+
+
+class SignalDetector:
+    def __init__(self, signals: list[BaseSignal]):
+        self.signals = signals
+
+    def detect_all(
+        self,
+        message: str,
+        response: str = None,
+        feedback: str = None,
+        memories: list[Memory] = None,
+    ) -> list[SignalEvent]:
+        """Run all signal detectors and return combined events."""
+        events = []
+        for signal in self.signals:
+            detected = signal.detect(
+                message=message,
+                response=response,
+                feedback=feedback,
+                memories=memories,
+            )
+            events.extend(detected)
+        return events