deepcq 0.1.0__tar.gz

deepcq-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,201 @@
+# 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/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-0.1.0/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-0.1.0/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__))