deepcq 0.1.0__py3-none-any.whl

deepcq/__init__.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from importlib import import_module
+
+__version__ = "0.1.0"
+
+_EXPORTS = {
+    "DeepCQ": ("deepcq.core", "DeepCQ"),
+    "MemorySchema": ("deepcq.schema", "MemorySchema"),
+    "QueryResult": ("deepcq.result", "QueryResult"),
+    "OptimizationMetrics": ("deepcq.result", "OptimizationMetrics"),
+    "AppState": ("deepcq.memory.state", "AppState"),
+    "SessionCache": ("deepcq.memory.session", "SessionCache"),
+    "History": ("deepcq.memory.session", "History"),
+    "LongTermStore": ("deepcq.memory.store", "LongTermStore"),
+    "ReferenceData": ("deepcq.memory.store", "ReferenceData"),
+}
+
+__all__ = [
+    "DeepCQ", "MemorySchema", "QueryResult", "OptimizationMetrics",
+    "AppState", "SessionCache", "History", "LongTermStore", "ReferenceData",
+]
+
+
+def __getattr__(name: str):
+    try:
+        module_name, attribute_name = _EXPORTS[name]
+    except KeyError as exc:
+        raise AttributeError(name) from None
+    module = import_module(module_name)
+    value = getattr(module, attribute_name)
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    return sorted(set(globals()) | set(__all__))

deepcq/core.py

@@ -0,0 +1,126 @@
+"""DeepCQ — main orchestrator."""
+from __future__ import annotations
+
+from .schema import MemorySchema
+from .intent import score_sections
+from .regex_gen import build_content_pattern, content_pattern_string
+from .result import QueryResult, OptimizationMetrics
+from .memory.state import AppState
+from .memory.session import SessionCache, History
+from .memory.store import LongTermStore, ReferenceData
+
+
+class DeepCQ:
+    """
+    Deep Context Query.
+
+    Manages five memory tiers and queries them dynamically using regex
+    patterns generated from the user's query. No domain knowledge is
+    baked in — the schema declares section names only.
+
+    Example::
+
+        from deepcq import DeepCQ, MemorySchema
+
+        schema = MemorySchema(sections=["status", "errors", "metrics"])
+        cq = DeepCQ(schema=schema)
+
+        cq.state.set("errors",  "[errors]\\n- OOM at 02:15\\n")
+        cq.state.set("metrics", "[metrics]\\nCPU: 78%\\nMemory: 4.2GB\\n")
+        cq.state.set("status",  "[status]\\nAll services running\\n")
+
+        result = cq.query("any memory or cpu spikes?")
+        print(result.content)
+        print(f"Reduction: {result.metrics.reduction_pct:.1f}%")
+    """
+
+    def __init__(
+        self,
+        schema: MemorySchema,
+        store_path: str | None = None,
+        reference_path: str | None = None,
+    ) -> None:
+        self.schema = schema
+        self.state = AppState()
+        self.cache = SessionCache()
+        self.history = History()
+        self.notes = LongTermStore(store_path)
+        self.reference = ReferenceData(reference_path)
+
+    def query(self, query: str) -> QueryResult:
+        """
+        Query all memory tiers and return only content relevant to the query.
+        """
+        tier_texts: dict[str, str] = {
+            "state":     self.state.as_text(),
+            "cache":     self.cache.as_text(),
+            "history":   self.history.as_text(),
+            "notes":     self.notes.as_text(),
+            "reference": self.reference.as_text(),
+        }
+
+        full_text = "\n".join(v for v in tier_texts.values() if v)
+        original_chars = len(full_text)
+
+        intent = score_sections(query, self.schema, tier_texts)
+
+        included: list[str] = []
+        excluded: list[str] = []
+        for section in self.schema.sections:
+            if intent.get(section, 0.0) >= self.schema.confidence_threshold:
+                included.append(section)
+            else:
+                excluded.append(section)
+
+        if not included and self.schema.fallback_include_all:
+            return QueryResult(
+                content=full_text,
+                intent=intent,
+                sections_included=list(self.schema.sections),
+                sections_excluded=[],
+                content_pattern=content_pattern_string(query),
+                metrics=OptimizationMetrics(
+                    original_chars=original_chars,
+                    filtered_chars=original_chars,
+                    reduction_pct=0.0,
+                ),
+            )
+
+        parts: list[str] = []
+
+        for section in included:
+            pat = self.schema.extraction_pattern(section)
+            for tier_name in ("state", "notes", "reference"):
+                text = tier_texts[tier_name]
+                if not text:
+                    continue
+                m = pat.search(text)
+                if m:
+                    parts.append(m.group(0).strip())
+
+        content_pat = build_content_pattern(query)
+        for tier_name in ("cache", "history"):
+            text = tier_texts[tier_name]
+            if text and content_pat.search(text):
+                parts.append(text.strip())
+
+        content = "\n\n".join(p for p in parts if p)
+        filtered_chars = len(content)
+        reduction_pct = (
+            round((1.0 - filtered_chars / original_chars) * 100, 1)
+            if original_chars > 0
+            else 0.0
+        )
+
+        return QueryResult(
+            content=content,
+            intent=intent,
+            sections_included=included,
+            sections_excluded=excluded,
+            content_pattern=content_pattern_string(query),
+            metrics=OptimizationMetrics(
+                original_chars=original_chars,
+                filtered_chars=filtered_chars,
+                reduction_pct=reduction_pct,
+            ),
+        )

deepcq/integrations/ternary/__init__.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from importlib import import_module
+
+_EXPORTS = {
+    "PromptLibrary": ("deepcq.integrations.ternary.prompt_library", "PromptLibrary"),
+    "ToolContextProvider": ("deepcq.integrations.ternary.adapters", "ToolContextProvider"),
+    "LangChainMemoryAdapter": ("deepcq.integrations.ternary.adapters", "LangChainMemoryAdapter"),
+}
+
+__all__ = ["PromptLibrary", "ToolContextProvider", "LangChainMemoryAdapter"]
+
+
+def __getattr__(name: str):
+	try:
+		module_name, attribute_name = _EXPORTS[name]
+	except KeyError:
+		raise AttributeError(name) from None
+	module = import_module(module_name)
+	value = getattr(module, attribute_name)
+	globals()[name] = value
+	return value
+
+
+def __dir__() -> list[str]:
+    return sorted(set(globals()) | set(__all__))

deepcq/integrations/ternary/adapters.py

@@ -0,0 +1,143 @@
+"""
+Adapters making DeepCQ usable as a memory/context backend for agent frameworks.
+
+ToolContextProvider  — formats QueryResult as a prompt-injectable context string.
+LangChainMemoryAdapter — duck-types LangChain's BaseChatMemory interface.
+
+Neither adapter imports LangChain or any other framework. They implement the
+interfaces by duck-typing so they work without installing any extras.
+"""
+from __future__ import annotations
+
+from deepcq import DeepCQ
+from .prompt_library import PromptLibrary
+
+
+class ToolContextProvider:
+    """
+    Formats DeepCQ query results as context strings for LLM prompts.
+
+    Matches the pattern used in ternary-ai/agents OpenAI Financial
+    Researcher Agent notebook: retrieve relevant context, inject into
+    the system prompt or tool schema before calling the LLM.
+
+    Example::
+
+        cq = DeepCQ(schema=schema)
+        provider = ToolContextProvider(cq)
+
+        # Before each LLM call:
+        context = provider.get_context("What is portfolio concentration risk?")
+        prompt = f"Use this context:\\n{context}\\n\\nQuestion: ..."
+    """
+
+    def __init__(self, cq: DeepCQ) -> None:
+        self._cq = cq
+
+    def get_context(self, query: str) -> str:
+        """Return filtered memory content relevant to the query."""
+        return self._cq.query(query).content
+
+    def get_prompt_template(self, query: str, library: PromptLibrary) -> str:
+        """
+        Retrieve the best matching prompt template(s) from a PromptLibrary
+        for the given query. Returns the raw template text with {variable}
+        placeholders intact — the caller fills them in.
+        """
+        return library.query(query).content
+
+    def get_context_with_template(
+        self, query: str, library: PromptLibrary
+    ) -> tuple[str, str]:
+        """
+        Convenience: return (memory_context, prompt_template) together.
+
+        Useful when you want to inject both retrieved state and a prompt
+        template into an LLM call in one step.
+        """
+        return self.get_context(query), self.get_prompt_template(query, library)
+
+
+class LangChainMemoryAdapter:
+    """
+    Makes DeepCQ usable as a LangChain chat memory component.
+
+    Duck-types the LangChain BaseChatMemory interface (save_context /
+    load_memory_variables / clear) without importing LangChain itself.
+    Drop it into any LangChain chain that accepts a memory= argument.
+
+    The adapter stores conversation turns in DeepCQ's History tier (T3)
+    and caches tool results in the SessionCache tier (T2). On each call to
+    load_memory_variables, it runs a deepcq query against the incoming
+    message to return only the most relevant prior context.
+
+    Example (LangChain)::
+
+        cq = DeepCQ(schema=schema)
+        memory = LangChainMemoryAdapter(cq)
+
+        chain = ConversationalRetrievalChain(
+            llm=llm,
+            retriever=retriever,
+            memory=memory,
+        )
+
+    Example (manual / OpenAI Agents SDK)::
+
+        memory.save_context({"input": user_msg}, {"output": agent_reply})
+        ctx = memory.load_memory_variables({"input": next_user_msg})
+        print(ctx["history"])  # filtered relevant context
+    """
+
+    memory_key: str = "history"
+
+    def __init__(self, cq: DeepCQ) -> None:
+        self._cq = cq
+
+    def save_context(self, inputs: dict, outputs: dict) -> None:
+        """Store one conversation turn (human + AI) in DeepCQ History."""
+        human = inputs.get("input") or inputs.get("human_input") or ""
+        ai = outputs.get("output") or outputs.get("response") or ""
+        if human:
+            self._cq.history.add("human", human)
+        if ai:
+            self._cq.history.add("ai", ai)
+
+    def load_memory_variables(self, inputs: dict) -> dict[str, str]:
+        """
+        Return filtered context relevant to the incoming message.
+
+        LangChain calls this before each LLM invocation. The returned dict
+        must have the key matching memory_key (default "history").
+        """
+        query = inputs.get("input") or inputs.get("human_input") or ""
+        result = self._cq.query(query) if query else None
+        content = result.content if result else self._cq.history.as_text()
+        return {self.memory_key: content}
+
+    def clear(self) -> None:
+        """Reset History and SessionCache (analogous to LangChain memory.clear())."""
+        self._cq.history.clear()
+        self._cq.cache.clear()
+
+    # LangChain also accesses these attributes on memory objects
+    @property
+    def chat_memory(self):
+        """Compatibility shim — returns an object with a messages property."""
+        turns = self._cq.history.turns()
+
+        class _Messages:
+            def __init__(self, turns):
+                self.messages = [
+                    {"role": t.role, "content": t.text} for t in turns
+                ]
+
+        return _Messages(turns)
+
+    @property
+    def output_key(self) -> str:
+        return "output"
+
+    @property
+    def input_key(self) -> str:
+        return "input"

deepcq/integrations/ternary/prompt_library.py

@@ -0,0 +1,170 @@
+"""
+PromptLibrary — loads ternary-ai/prompts CSVs into queryable deepcq memory.
+
+Each CSV file becomes one schema section. Each non-empty line in the CSV
+becomes one prompt entry in that section. Prompt templates may contain
+{variable} placeholders — these are stored and returned verbatim.
+
+Usage::
+
+    from deepcq.integrations.ternary import PromptLibrary
+
+    # From a local clone of ternary-ai/prompts:
+    lib = PromptLibrary.from_local("/path/to/ternary-ai/prompts/")
+
+    # From raw GitHub URLs (uses urllib, no extra deps):
+    lib = PromptLibrary.from_urls(PromptLibrary.DEFAULT_URLS)
+
+    result = lib.query("portfolio concentration risk")
+    print(result.sections_included)   # e.g. ["risk-management", "portfolio"]
+    print(result.content)             # matching prompt templates
+"""
+from __future__ import annotations
+
+import csv
+import io
+from pathlib import Path
+from typing import Iterable
+
+from deepcq import DeepCQ, MemorySchema, QueryResult
+
+
+_BASE_URL = "https://raw.githubusercontent.com/ternary-ai/prompts/main/"
+
+SECTIONS = [
+    "agents",
+    "analysis",
+    "concepts",
+    "content",
+    "journal",
+    "knowledgegraphs",
+    "named-entities",
+    "portfolio",
+    "research",
+    "risk-management",
+    "scenario-analysis",
+    "summarization",
+    "trading",
+]
+
+DEFAULT_URLS: dict[str, str] = {s: f"{_BASE_URL}{s}.csv" for s in SECTIONS}
+
+
+class PromptLibrary:
+    """
+    Queryable library of ternary-ai financial prompt templates.
+
+    Wraps DeepCQ with a schema whose sections map 1-to-1 to the CSV files
+    in the ternary-ai/prompts repository. Querying returns only the
+    sections whose stored prompts are most relevant to the user's query.
+    """
+
+    SECTIONS = SECTIONS
+    DEFAULT_URLS = DEFAULT_URLS
+
+    def __init__(self) -> None:
+        schema = MemorySchema(
+            sections=self.SECTIONS,
+            section_header_format="[{name}]",
+            confidence_threshold=0.25,  # broader recall for prompt retrieval
+            fallback_include_all=False,  # don't dump everything on vague queries
+        )
+        self._cq = DeepCQ(schema=schema)
+        self._loaded: set[str] = set()
+
+    # ------------------------------------------------------------------
+    # Loading helpers
+    # ------------------------------------------------------------------
+
+    def load_section(self, section: str, rows: Iterable[str]) -> None:
+        """Store a list of prompt strings into the named section."""
+        lines = [r.strip() for r in rows if r.strip()]
+        if not lines:
+            return
+        body = "\n".join(lines)
+        self._cq.state.set(section, f"[{section}]\n{body}\n")
+        self._loaded.add(section)
+
+    def load_text(self, section: str, raw: str) -> None:
+        """Parse raw CSV text (one prompt per line) and load into section."""
+        reader = csv.reader(io.StringIO(raw))
+        prompts: list[str] = []
+        for row in reader:
+            # Each row may be a single cell or bare line
+            text = " ".join(row).strip()
+            if text:
+                prompts.append(text)
+        self.load_section(section, prompts)
+
+    # ------------------------------------------------------------------
+    # Factory methods
+    # ------------------------------------------------------------------
+
+    @classmethod
+    def from_local(cls, directory: str | Path) -> "PromptLibrary":
+        """
+        Load all CSV files from a local clone of ternary-ai/prompts.
+
+        Only files whose stem matches a known section name are loaded.
+        """
+        lib = cls()
+        base = Path(directory)
+        for section in cls.SECTIONS:
+            path = base / f"{section}.csv"
+            if path.exists():
+                lib.load_text(section, path.read_text(encoding="utf-8"))
+        return lib
+
+    @classmethod
+    def from_urls(
+        cls,
+        url_map: dict[str, str] | None = None,
+        timeout: int = 10,
+    ) -> "PromptLibrary":
+        """
+        Fetch CSV files from raw GitHub URLs using urllib (stdlib only).
+
+        Defaults to ternary-ai/prompts on GitHub. Pass a custom url_map to
+        override individual sections or point to a fork.
+
+        Args:
+            url_map: section_name → raw URL. Defaults to DEFAULT_URLS.
+            timeout: HTTP request timeout in seconds.
+        """
+        import urllib.request
+        from urllib.parse import urlparse
+
+        lib = cls()
+        urls = url_map if url_map is not None else cls.DEFAULT_URLS
+
+        for section, url in urls.items():
+            if urlparse(url).scheme not in ("http", "https"):
+                print(
+                    f"[deepcq] Warning: refusing to load '{section}' from {url}: "
+                    "only http/https URLs are allowed"
+                )
+                continue
+            try:
+                with urllib.request.urlopen(url, timeout=timeout) as resp:
+                    raw = resp.read().decode("utf-8")
+                lib.load_text(section, raw)
+            except Exception as exc:
+                # Non-fatal: skip sections that fail to fetch
+                print(f"[deepcq] Warning: could not load '{section}' from {url}: {exc}")
+
+        return lib
+
+    # ------------------------------------------------------------------
+    # Query interface
+    # ------------------------------------------------------------------
+
+    def query(self, text: str) -> QueryResult:
+        """Return the prompt templates most relevant to the query."""
+        return self._cq.query(text)
+
+    def loaded_sections(self) -> list[str]:
+        """Sections that have been successfully loaded."""
+        return sorted(self._loaded)
+
+    def __repr__(self) -> str:
+        return f"PromptLibrary(loaded={self.loaded_sections()})"

deepcq/intent.py

@@ -0,0 +1,51 @@
+"""Two-phase section relevance scorer."""
+from __future__ import annotations
+from .schema import MemorySchema
+from .tokens import tokenize
+
+
+def score_sections(
+    query: str,
+    schema: MemorySchema,
+    tier_texts: dict[str, str],
+) -> dict[str, float]:
+    """
+    Score each schema section for relevance to the query.
+
+    For each section we build a vocabulary from three sources:
+      1. The section name tokens (and optional schema keywords).
+      2. The tokenized content of that section's stored text.
+
+    Score = proportion of unique query tokens found in the section vocabulary.
+
+    This is query-term-first: the patterns come from the query itself —
+    no keyword lists are required. Optional schema keywords extend the
+    vocabulary for sections whose names are abbreviations or jargon.
+    """
+    query_tokens = set(tokenize(query, include_stems=True))
+    if not query_tokens:
+        return {s: 0.0 for s in schema.sections}
+
+    scores: dict[str, float] = {}
+
+    for section in schema.sections:
+        vocab: set[str] = set()
+
+        vocab.update(tokenize(section, include_stems=True))
+
+        for kw in schema.keywords.get(section, []):
+            vocab.update(tokenize(kw, include_stems=True))
+
+        pat = schema.extraction_pattern(section)
+        for text in tier_texts.values():
+            if not text:
+                continue
+            m = pat.search(text)
+            if m:
+                vocab.update(tokenize(m.group(0), include_stems=True))
+
+        matched = query_tokens & vocab
+        score = round(len(matched) / len(query_tokens), 4)
+        scores[section] = score
+
+    return scores

deepcq/memory/__init__.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from importlib import import_module
+
+_EXPORTS = {
+    "AppState": ("deepcq.memory.state", "AppState"),
+    "SessionCache": ("deepcq.memory.session", "SessionCache"),
+    "History": ("deepcq.memory.session", "History"),
+    "LongTermStore": ("deepcq.memory.store", "LongTermStore"),
+    "ReferenceData": ("deepcq.memory.store", "ReferenceData"),
+}
+
+__all__ = ["AppState", "SessionCache", "History", "LongTermStore", "ReferenceData"]
+
+
+def __getattr__(name: str):
+	try:
+		module_name, attribute_name = _EXPORTS[name]
+	except KeyError:
+		raise AttributeError(name) from None
+	module = import_module(module_name)
+	value = getattr(module, attribute_name)
+	globals()[name] = value
+	return value
+
+
+def __dir__() -> list[str]:
+    return sorted(set(globals()) | set(__all__))

deepcq/memory/session.py

@@ -0,0 +1,62 @@
+"""T2 — SessionCache and T3 — History."""
+from __future__ import annotations
+from collections import deque
+from typing import NamedTuple
+
+
+class SessionCache:
+    """T2 — Ephemeral per-session cache. Deduplicates repeated (key, value) puts."""
+
+    def __init__(self, max_entries: int = 30) -> None:
+        self._max = max_entries
+        self._entries: dict[str, str] = {}
+        self._order: list[str] = []
+
+    def put(self, key: str, value: str) -> None:
+        if self._entries.get(key) == value:
+            return
+        if key in self._order:
+            self._order.remove(key)
+        self._entries[key] = value
+        self._order.append(key)
+        while len(self._order) > self._max:
+            evicted = self._order.pop(0)
+            self._entries.pop(evicted, None)
+
+    def get(self, key: str) -> str | None:
+        return self._entries.get(key)
+
+    def as_text(self) -> str:
+        if not self._entries:
+            return ""
+        return "\n".join(f"[cache:{k}]\n{v}" for k, v in self._entries.items())
+
+    def clear(self) -> None:
+        self._entries.clear()
+        self._order.clear()
+
+
+class Turn(NamedTuple):
+    role: str
+    text: str
+
+
+class History:
+    """T3 — Sliding conversation window. Default: 6 turns."""
+
+    def __init__(self, max_turns: int = 6) -> None:
+        self._turns: deque[Turn] = deque(maxlen=max_turns)
+
+    def add(self, role: str, text: str) -> None:
+        self._turns.append(Turn(role=role, text=text))
+
+    def turns(self) -> list[Turn]:
+        return list(self._turns)
+
+    def as_text(self) -> str:
+        if not self._turns:
+            return ""
+        return "\n\n".join(f"{t.role.upper()}: {t.text}" for t in self._turns)
+
+    def clear(self) -> None:
+        self._turns.clear()

deepcq/memory/state.py

@@ -0,0 +1,37 @@
+"""T1 — Live application state."""
+from __future__ import annotations
+
+
+class AppState:
+    """
+    Primary memory tier: the current state of the running application.
+
+    Each section is stored as raw text that includes its own header, e.g.::
+
+        state.set("errors", "[errors]\\n- OOM at 02:15\\n")
+        state.set("metrics", "[metrics]\\nCPU: 78%\\n")
+    """
+
+    def __init__(self) -> None:
+        self._sections: dict[str, str] = {}
+
+    def set(self, section: str, text: str) -> None:
+        self._sections[section] = text
+
+    def get(self, section: str) -> str:
+        return self._sections.get(section, "")
+
+    def remove(self, section: str) -> None:
+        self._sections.pop(section, None)
+
+    def sections(self) -> list[str]:
+        return list(self._sections.keys())
+
+    def as_text(self) -> str:
+        return "\n".join(self._sections.values())
+
+    def as_dict(self) -> dict[str, str]:
+        return dict(self._sections)
+
+    def clear(self) -> None:
+        self._sections.clear()

deepcq/memory/store.py

@@ -0,0 +1,82 @@
+"""T4 — LongTermStore and T5 — ReferenceData."""
+from __future__ import annotations
+import json
+from pathlib import Path
+
+
+class LongTermStore:
+    """T4 — Persistent, append-only notes store. File-backed when path given."""
+
+    def __init__(self, path: str | Path | None = None) -> None:
+        self._path = Path(path) if path else None
+        self._data: dict[str, list[str]] = {}
+        if self._path and self._path.exists():
+            self._load()
+
+    def append(self, key: str, text: str) -> None:
+        self._data.setdefault(key, []).append(text)
+        if self._path:
+            self._save()
+
+    def get(self, key: str) -> list[str]:
+        return list(self._data.get(key, []))
+
+    def keys(self) -> list[str]:
+        return list(self._data.keys())
+
+    def as_text(self) -> str:
+        if not self._data:
+            return ""
+        parts: list[str] = []
+        for key, entries in self._data.items():
+            parts.append(f"[notes:{key}]")
+            parts.extend(entries)
+        return "\n".join(parts)
+
+    def _load(self) -> None:
+        try:
+            self._data = json.loads(self._path.read_text())
+        except (json.JSONDecodeError, OSError):
+            self._data = {}
+
+    def _save(self) -> None:
+        if self._path:
+            self._path.parent.mkdir(parents=True, exist_ok=True)
+            self._path.write_text(json.dumps(self._data, indent=2))
+
+
+class ReferenceData:
+    """T5 — Lazy-loaded reference / configuration data. File-backed when path given."""
+
+    def __init__(self, path: str | Path | None = None) -> None:
+        self._path = Path(path) if path else None
+        self._data: dict | None = None
+
+    def _ensure_loaded(self) -> None:
+        if self._data is None:
+            if self._path and self._path.exists():
+                try:
+                    self._data = json.loads(self._path.read_text())
+                except (json.JSONDecodeError, OSError):
+                    self._data = {}
+            else:
+                self._data = {}
+
+    def get(self, key: str, default=None):
+        self._ensure_loaded()
+        return self._data.get(key, default)
+
+    def set(self, key: str, value) -> None:
+        self._ensure_loaded()
+        self._data[key] = value
+        if self._path:
+            self._path.parent.mkdir(parents=True, exist_ok=True)
+            self._path.write_text(json.dumps(self._data, indent=2))
+
+    def as_text(self) -> str:
+        self._ensure_loaded()
+        if not self._data:
+            return ""
+        lines = ["[reference]"]
+        lines.extend(f"{k}: {v}" for k, v in self._data.items())
+        return "\n".join(lines)

deepcq/regex_gen.py

@@ -0,0 +1,22 @@
+"""Dynamic regex pattern builder from query tokens."""
+from __future__ import annotations
+import re
+import functools
+from .tokens import tokenize
+
+
+@functools.lru_cache(maxsize=512)
+def _compile_content_pattern(token_tuple: tuple[str, ...]) -> re.Pattern[str]:
+    if not token_tuple:
+        return re.compile(r"(?!)")
+    escaped = [re.escape(t) for t in sorted(token_tuple, key=len, reverse=True)]
+    return re.compile(r"\b(" + "|".join(escaped) + r")\b", re.IGNORECASE)
+
+
+def build_content_pattern(query: str) -> re.Pattern[str]:
+    tokens = tuple(sorted(set(tokenize(query, include_stems=True))))
+    return _compile_content_pattern(tokens)
+
+
+def content_pattern_string(query: str) -> str:
+    return build_content_pattern(query).pattern

deepcq/result.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+from dataclasses import dataclass
+
+
+@dataclass
+class OptimizationMetrics:
+    original_chars: int
+    filtered_chars: int
+    reduction_pct: float
+
+
+@dataclass
+class QueryResult:
+    content: str
+    intent: dict[str, float]
+    sections_included: list[str]
+    sections_excluded: list[str]
+    content_pattern: str
+    metrics: OptimizationMetrics

deepcq/schema.py

@@ -0,0 +1,62 @@
+"""MemorySchema — defines section names and optional keyword overrides."""
+from __future__ import annotations
+import re
+from dataclasses import dataclass, field
+from typing import Sequence
+
+
+@dataclass
+class MemorySchema:
+    """
+    Declares the logical sections that structure stored memory text.
+
+    sections:
+        List of section names, e.g. ["errors", "metrics", "status"].
+        No keyword lists required — deepcq derives patterns from the
+        query itself (query-term-first approach).
+
+    keywords:
+        Optional per-section extra terms that boost relevance scoring.
+        Useful when section names are abbreviations or jargon.
+
+    section_header_format:
+        How sections are delimited in stored text.
+        Default "[{name}]" means sections look like "[errors]", "[metrics]".
+
+    confidence_threshold:
+        Minimum score (0.0–1.0) for a section to be included.
+
+    fallback_include_all:
+        When True (default), return all content unfiltered if no section
+        scores above the threshold. Prevents silent data loss.
+    """
+
+    sections: Sequence[str]
+    keywords: dict[str, list[str]] = field(default_factory=dict)
+    section_header_format: str = "[{name}]"
+    confidence_threshold: float = 0.3
+    fallback_include_all: bool = True
+
+    def __post_init__(self) -> None:
+        name_idx = self.section_header_format.index("{name}")
+        self._prefix = self.section_header_format[:name_idx]
+
+        escaped_prefix = re.escape(self._prefix)
+        lookahead = rf"(?=\n{escaped_prefix}|\Z)"
+
+        self._extraction_patterns: dict[str, re.Pattern[str]] = {}
+        for section in self.sections:
+            header = self.section_header_format.format(name=section)
+            pat = re.compile(
+                rf"({re.escape(header)}.*?){lookahead}",
+                re.DOTALL | re.IGNORECASE,
+            )
+            self._extraction_patterns[section] = pat
+
+        self._id = hash((tuple(self.sections), self.section_header_format))
+
+    def extraction_pattern(self, section: str) -> re.Pattern[str]:
+        return self._extraction_patterns[section]
+
+    def schema_id(self) -> int:
+        return self._id

deepcq/tokens.py

@@ -0,0 +1,85 @@
+"""Query tokenizer and suffix-strip stemmer. No external dependencies."""
+from __future__ import annotations
+import re
+
+_STOPWORDS = frozenset({
+    "a", "an", "the", "and", "or", "but", "in", "on", "at", "to", "for",
+    "of", "with", "by", "from", "is", "are", "was", "were", "be", "been",
+    "being", "have", "has", "had", "do", "does", "did", "will", "would",
+    "could", "should", "may", "might", "shall", "can", "it", "its",
+    "this", "that", "these", "those", "i", "me", "my", "we", "our",
+    "you", "your", "he", "she", "him", "her", "his", "hers", "they",
+    "them", "their", "what", "which", "who", "whom", "how", "when",
+    "where", "why", "all", "any", "both", "each", "few", "more", "most",
+    "other", "some", "such", "no", "not", "only", "same", "so", "than",
+    "too", "very", "just", "about", "up", "down", "out", "if", "then",
+    "as", "also", "into", "through", "during", "before", "after",
+    "above", "below", "between", "while", "although", "because", "since",
+    "until", "unless", "however", "therefore", "there", "here", "now",
+    "show", "tell", "get", "give", "let", "make", "see", "know", "go",
+    "come", "think", "say", "want", "look", "use", "find", "take",
+    "much", "many", "lot", "like", "new", "good", "right", "old",
+    "long", "little", "own", "first", "last", "next", "back", "over",
+    "again", "once", "am", "s", "re", "ve", "ll", "d", "please",
+})
+
+# Ordered longest-first so greedier matches win.
+# "es" is intentionally omitted: "spikes"→"spike" via "s" rule is correct;
+# "es" would give "spik" which is worse for content matching.
+_SUFFIX_RULES: list[tuple[str, str]] = [
+    ("ational", "ate"), ("tional", "tion"), ("izing", "ize"),
+    ("ising", "ise"), ("ization", "ize"), ("isation", "ise"),
+    ("nesses", "ness"), ("iness", "y"), ("ations", "ate"),
+    ("tion", ""), ("ions", ""), ("ing", ""), ("ous", ""),
+    ("ive", ""), ("ful", ""), ("ness", ""), ("less", ""),
+    ("able", ""), ("ible", ""), ("ment", ""), ("ance", ""),
+    ("ence", ""), ("ion", ""), ("ies", "y"), ("ves", "f"),
+    ("ed", ""), ("er", ""), ("ly", ""), ("s", ""),
+]
+
+_MIN_ROOT = 3
+_VOWELS = frozenset("aeiou")
+
+
+def _dedouble(root: str) -> str:
+    """Remove a doubled terminal consonant produced by suffix stripping.
+
+    e.g. "runn" (from running) → "run", "bugg" (from bugged) → "bug".
+    """
+    if len(root) >= 2 and root[-1] == root[-2] and root[-1] not in _VOWELS:
+        return root[:-1]
+    return root
+
+
+def stem(token: str) -> str:
+    """Return a suffix-stripped root form with doubled-consonant cleanup."""
+    for suffix, replacement in _SUFFIX_RULES:
+        if token.endswith(suffix) and len(token) - len(suffix) >= _MIN_ROOT:
+            root = token[: len(token) - len(suffix)] + replacement
+            if replacement == "":
+                root = _dedouble(root)
+            return root
+    return token
+
+
+def tokenize(text: str, include_stems: bool = True) -> list[str]:
+    """
+    Lowercase, strip punctuation, drop stopwords.
+    With include_stems=True each unique token is followed by its stemmed
+    form (if different), giving the caller both surface and root forms.
+    """
+    words = re.findall(r"[a-zA-Z][a-zA-Z0-9]*", text.lower())
+    seen: set[str] = set()
+    result: list[str] = []
+    for w in words:
+        if w in _STOPWORDS or len(w) < 2:
+            continue
+        if w not in seen:
+            seen.add(w)
+            result.append(w)
+        if include_stems:
+            s = stem(w)
+            if s and s != w and s not in seen and len(s) >= _MIN_ROOT:
+                seen.add(s)
+                result.append(s)
+    return result

deepcq-0.1.0.dist-info/METADATA

@@ -0,0 +1,220 @@
+Metadata-Version: 2.4
+Name: deepcq
+Version: 0.1.0
+Summary: Deep Context Query — intent-aware memory querying for LLM agents
+License: MIT
+Project-URL: Homepage, https://github.com/ternary-ai/deepcq
+Project-URL: Repository, https://github.com/ternary-ai/deepcq
+Project-URL: Issues, https://github.com/ternary-ai/deepcq/issues
+Keywords: llm,agents,memory,context,rag,prompt-engineering
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Dynamic: license-file
+
+# deepcq
+
+**Deep Context Query** — intent-aware memory querying for LLM agents.
+
+deepcq sits between an agent's memory and its prompt. Instead of stuffing an
+entire memory blob into every LLM call, it scores which sections of memory
+are actually relevant to the current query and returns only those — cutting
+prompt size while keeping recall.
+
+No embeddings, no vector store, no external dependencies. Relevance is
+computed from the query's own tokens against text already in memory, using
+plain regex and a lightweight stemmer.
+
+## Install
+
+```bash
+pip install deepcq
+```
+
+For local development from a clone:
+
+```bash
+cd deepcq
+pip install -e ".[dev]"
+```
+
+## Core idea
+
+You declare a `MemorySchema`: a list of section names such as
+`["status", "errors", "metrics"]`. deepcq doesn't need to know what those
+sections mean — it derives what's relevant from the words in each query
+itself ("query-term-first"), rather than from a hand-built keyword table.
+
+```python
+from deepcq import DeepCQ, MemorySchema
+
+schema = MemorySchema(sections=["status", "errors", "metrics"])
+cq = DeepCQ(schema=schema)
+
+cq.state.set("errors",  "[errors]\n- OOM at 02:15\n")
+cq.state.set("metrics", "[metrics]\nCPU: 78%\nMemory: 4.2GB\n")
+cq.state.set("status",  "[status]\nAll services running\n")
+
+result = cq.query("any memory or cpu spikes?")
+print(result.content)                       # only the metrics section
+print(result.sections_included)             # ["metrics"]
+print(f"{result.metrics.reduction_pct:.1f}% smaller")
+```
+
+## How it works
+
+### 1. Five memory tiers
+
+`DeepCQ` manages five tiers, each suited to a different memory lifetime:
+
+| Tier | Class | Lifetime | Purpose |
+|------|-------|----------|---------|
+| T1 | `AppState` | live | Current state of the running application (sections keyed by name) |
+| T2 | `SessionCache` | per-session, bounded | Ephemeral key/value scratch space, deduped, LRU-evicted |
+| T3 | `History` | sliding window | Last N conversation turns |
+| T4 | `LongTermStore` | persistent | Append-only notes, optionally file-backed (JSON) |
+| T5 | `ReferenceData` | persistent, lazy | Static config/reference data, optionally file-backed |
+
+Each tier renders itself to text via `as_text()`. `DeepCQ.query()` pulls text
+from all five tiers before scoring.
+
+### 2. Tokenizing the query (`tokens.py`)
+
+The query is lowercased, split into words, stripped of stopwords, and each
+surviving token is paired with a suffix-stripped stem (`spikes` → `spike`,
+`running` → `run`). No external NLP dependency — it's a small suffix-rule
+table plus a doubled-consonant cleanup (`running` → `runn` → `run`).
+
+### 3. Scoring sections (`intent.py`)
+
+For each section in the schema, deepcq builds a vocabulary from:
+1. The section name itself (tokenized/stemmed).
+2. Optional `keywords` you declare for that section in the schema (useful
+   when a section name is jargon, e.g. `"db"` → `["database", "postgres"]`).
+3. Whatever text is currently stored under that section's header across all
+   tiers.
+
+The section's score is the fraction of unique query tokens found in that
+vocabulary. Sections scoring at or above `schema.confidence_threshold`
+(default `0.3`) are "included".
+
+### 4. Extracting content (`schema.py`, `regex_gen.py`)
+
+Sections are delimited in stored text by a header, `"[{name}]"` by default
+(configurable via `section_header_format`, e.g. `"## {name}"`). Each section
+compiles to a regex that captures from its header up to the next header or
+end of string — this is how `MemorySchema.extraction_pattern(section)` pulls
+a section's block out of raw tier text.
+
+For the two free-text tiers (`cache`, `history`, which aren't
+section-delimited), deepcq instead builds a single regex out of all query
+tokens and includes that tier's text only if any token matches
+(`build_content_pattern` in `regex_gen.py`).
+
+### 5. Result (`result.py`)
+
+`query()` returns a `QueryResult`:
+
+```python
+@dataclass
+class QueryResult:
+    content: str                      # the filtered, concatenated text
+    intent: dict[str, float]          # per-section relevance scores
+    sections_included: list[str]
+    sections_excluded: list[str]
+    content_pattern: str              # the regex used against cache/history
+    metrics: OptimizationMetrics      # original_chars, filtered_chars, reduction_pct
+```
+
+### Fallback safety
+
+If no section clears the confidence threshold and
+`schema.fallback_include_all` is `True` (the default), `query()` returns the
+full unfiltered text instead of nothing — this prevents a vague query from
+silently discarding memory the agent might actually need.
+
+## Package layout
+
+```
+deepcq/
+├── pyproject.toml
+├── README.md
+├── deepcq/                      # the installable package
+│   ├── __init__.py              # public API: DeepCQ, MemorySchema, QueryResult, ...
+│   ├── core.py                  # DeepCQ orchestrator (query())
+│   ├── schema.py                # MemorySchema + extraction regex compilation
+│   ├── intent.py                # score_sections()
+│   ├── tokens.py                # tokenize() / stem()
+│   ├── regex_gen.py              # query-token regex builder for free-text tiers
+│   ├── result.py                # QueryResult / OptimizationMetrics dataclasses
+│   ├── memory/
+│   │   ├── state.py             # T1 AppState
+│   │   ├── session.py           # T2 SessionCache, T3 History
+│   │   └── store.py             # T4 LongTermStore, T5 ReferenceData
+│   └── integrations/
+│       └── ternary/             # optional adapter for ternary-ai agents/prompts
+│           ├── adapters.py      # ToolContextProvider, LangChainMemoryAdapter
+│           └── prompt_library.py # PromptLibrary (loads ternary-ai/prompts CSVs)
+├── examples/
+│   ├── openai_agents_sdk.py
+│   ├── claude_agents_sdk.py
+│   ├── qwen_agents_sdk.py
+│   └── google_a2a.py
+└── tests/
+```
+
+## Optional integrations
+
+`deepcq.integrations.ternary` is an optional adapter layer for using deepcq
+as a memory/context backend in agent frameworks. It has no hard dependency
+on any framework — both adapters duck-type the interface they mimic:
+
+- **`ToolContextProvider`** — formats a `QueryResult` as a plain string to
+  inject into a system prompt or tool call.
+- **`LangChainMemoryAdapter`** — duck-types LangChain's `BaseChatMemory`
+  (`save_context` / `load_memory_variables` / `clear`), so it can be passed
+  directly as a chain's `memory=` argument without installing LangChain.
+- **`PromptLibrary`** — loads the CSV prompt templates from the
+  [ternary-ai/prompts](https://github.com/ternary-ai/prompts) repo (locally
+  or via `urllib` from raw GitHub URLs) into a deepcq schema, so prompt
+  templates themselves can be retrieved by intent.
+
+```python
+from deepcq import DeepCQ, MemorySchema
+from deepcq.integrations.ternary import ToolContextProvider, PromptLibrary
+
+cq = DeepCQ(schema=MemorySchema(sections=["research", "risk-management"]))
+provider = ToolContextProvider(cq)
+context = provider.get_context("what is my portfolio concentration risk?")
+```
+
+See `examples/openai_agents_sdk.py`, `examples/claude_agents_sdk.py`,
+`examples/qwen_agents_sdk.py`, and `examples/google_a2a.py` for focused
+integration examples. They are designed as SDK wiring references, so you
+may need to adjust the exact import path to match the SDK version you have
+installed.
+
+## Testing
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## Moving this into its own repository
+
+This directory is self-contained — nothing outside `deepcq/` is required.
+To split it out:
+
+```bash
+cp -r deepcq/ /path/to/new/deepcq-repo
+cd /path/to/new/deepcq-repo
+git init
+pip install -e ".[dev]"
+pytest
+```

deepcq-0.1.0.dist-info/RECORD

@@ -0,0 +1,20 @@
+deepcq/__init__.py,sha256=28J347FSAfusuTH-8MDRfTJlicHulRmQJEQOGITqDzE,1157
+deepcq/core.py,sha256=vs5B7ILnTnKXy46Relt2xvdRR08zMbVv1ZjvcgFBm8E,4340
+deepcq/intent.py,sha256=9ly-C_gVrHx9gU_Ctzb9_R74C0hWkM8RSIEfHvdvLo4,1642
+deepcq/regex_gen.py,sha256=ulWhnQr6YISS-Lyl6njqGYlgSKTc-8Mjl6-YRKVzGwY,745
+deepcq/result.py,sha256=aSVDwCCSBAQF0Q4fBjKnNA_QRESmS2PNSxg9l8Pav-Y,384
+deepcq/schema.py,sha256=nj8CEMst4zq9fMgKl-vaqxA6QEXAKbnmr7VFSgmM1O4,2172
+deepcq/tokens.py,sha256=XPYelX-nbSlQAO26moZ0HMijIQzk9ah9NSe4X-Tc6_o,3629
+deepcq/integrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+deepcq/integrations/ternary/__init__.py,sha256=QZKZafC5QxBhw1S-8CATAEDc7IjaKXtkpLKTiQ40pAs,778
+deepcq/integrations/ternary/adapters.py,sha256=AQLKpm5NKxBD9s_xYVZhS1E3NuMKYZmF88K6GciCRzo,4999
+deepcq/integrations/ternary/prompt_library.py,sha256=jZYYChy9AfUnAMNF5X4qsy3ebQU1HD4J9ib8eyNysHM,5742
+deepcq/memory/__init__.py,sha256=h2as2ZhLCORFpcrgu6GJpNC3LnneVlrNtsnhhmyE3yA,804
+deepcq/memory/session.py,sha256=09amEaF9Dsb4ztP-AKhtq8zEy8cNkm1O0WLbes7wdNM,1766
+deepcq/memory/state.py,sha256=mpqtwZ4jwLkxUWRItwSpXmrKxQgYUF6zHTsyMszT_E8,1016
+deepcq/memory/store.py,sha256=1ILyTXEWHsWzGBCueon-6XpmYhl6n089WwAO8LBA6hI,2648
+deepcq-0.1.0.dist-info/licenses/LICENSE,sha256=XoHDFJshSHmLHwGhVEXsU8sI3oIqCLvZnfu0-h8C4m4,1067
+deepcq-0.1.0.dist-info/METADATA,sha256=0fWYLPk_95Ab0eZ2Ac5WA_trHtQUrGFriOZkryOnhaM,8507
+deepcq-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+deepcq-0.1.0.dist-info/top_level.txt,sha256=FfVfEANDQkJ__PFSyHZq5r8oKAwaDzMtLS9MXzdiEwI,7
+deepcq-0.1.0.dist-info/RECORD,,

deepcq-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

deepcq-0.1.0.dist-info/licenses/LICENSE

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

deepcq-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+deepcq