rotalabs-context 1.0.0__tar.gz

rotalabs_context-1.0.0/LICENSE

@@ -0,0 +1,3 @@
+GNU Affero General Public License v3.0
+
+See https://www.gnu.org/licenses/agpl-3.0.en.html for full text.

rotalabs_context-1.0.0/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: rotalabs-context
+Version: 1.0.0
+Summary: Context intelligence for AI agents - Ingest, search, and subscribe to shared context across your AI systems
+Project-URL: Homepage, https://rotalabs.ai
+Project-URL: Repository, https://github.com/rotalabs/rotalabs-context
+Project-URL: Documentation, https://rotalabs.ai/docs/context
+Author-email: Subhadip Mitra <subhadip@rotalabs.ai>, Rotalabs Research <research@rotalabs.ai>
+License-Expression: AGPL-3.0-or-later
+License-File: LICENSE
+Keywords: ai-agents,context,context-engine,embeddings,etl,knowledge-graph,rag,semantic-search
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: airflow
+Requires-Dist: apache-airflow>=2.5.0; extra == 'airflow'
+Provides-Extra: all
+Requires-Dist: httpx>=0.25.0; extra == 'all'
+Requires-Dist: numpy>=1.24.0; extra == 'all'
+Requires-Dist: rotalabs[telemetry]>=1.0.0; extra == 'all'
+Requires-Dist: sentence-transformers>=2.2.0; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.5.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
+Requires-Dist: pytest>=7.4.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: local
+Requires-Dist: numpy>=1.24.0; extra == 'local'
+Requires-Dist: sentence-transformers>=2.2.0; extra == 'local'
+Provides-Extra: platform
+Requires-Dist: httpx>=0.25.0; extra == 'platform'
+Provides-Extra: telemetry
+Requires-Dist: rotalabs[telemetry]>=1.0.0; extra == 'telemetry'
+Description-Content-Type: text/markdown
+
+# rotalabs-context
+
+> Context intelligence for AI agents — Ingest, search, and subscribe to shared context across your AI systems.
+
+Part of the [Rotalabs](https://rotalabs.ai) trust intelligence research ecosystem.
+
+## Installation
+
+```bash
+pip install rotalabs-context
+```
+
+With local embedding support:
+```bash
+pip install rotalabs-context[local]
+```
+
+With Rotascale platform integration:
+```bash
+pip install rotalabs-context[platform]
+```
+
+## Quick Start
+
+```python
+from rotalabs_context import ContextEngine
+
+# Local mode (zero config, SQLite backend)
+ctx = ContextEngine()
+
+# Platform mode (connects to Rotascale)
+ctx = ContextEngine(
+    api_key="rot_...",
+    base_url="https://api.rotascale.com",
+)
+
+# Ingest context
+result = ctx.ingest(
+    records=[
+        {"content": "User reported login issue", "title": "Support ticket #1234"},
+        {"content": "Auth service latency spike at 2pm UTC", "title": "Incident report"},
+    ],
+    source="helpdesk",
+    tags=["support", "auth"],
+    scope="team:support",
+)
+
+# Search
+results = ctx.search("login issues", top_k=5, mode="semantic")
+for hit in results:
+    print(f"{hit.score:.2f} — {hit.title}")
+
+# Subscribe to context updates
+ctx.on("context.created", filter={"tags": ["support"]}, callback=my_handler)
+```
+
+## Features
+
+- **Ingest**: Push data from any pipeline; we add the "C" (embeddings, entities, relationships)
+- **Search**: Semantic + keyword + hybrid search across all ingested context
+- **Subscribe**: Real-time context propagation via events
+- **ACLs**: Scope-based access control (global, team, agent, project, user)
+- **Pluggable backends**: SQLite (local), PostgreSQL (self-hosted), Rotascale Platform (managed)
+
+## Pipeline Adapters
+
+```python
+# Airflow
+from rotalabs_context.adapters import AirflowContextOperator
+
+# In your DAG
+ingest_task = AirflowContextOperator(
+    task_id="ingest_to_context",
+    source="airflow-etl",
+    tags=["daily-batch"],
+)
+```
+
+## License
+
+AGPL-3.0 — See [LICENSE](LICENSE) for details.

rotalabs_context-1.0.0/README.md

@@ -0,0 +1,81 @@
+# rotalabs-context
+
+> Context intelligence for AI agents — Ingest, search, and subscribe to shared context across your AI systems.
+
+Part of the [Rotalabs](https://rotalabs.ai) trust intelligence research ecosystem.
+
+## Installation
+
+```bash
+pip install rotalabs-context
+```
+
+With local embedding support:
+```bash
+pip install rotalabs-context[local]
+```
+
+With Rotascale platform integration:
+```bash
+pip install rotalabs-context[platform]
+```
+
+## Quick Start
+
+```python
+from rotalabs_context import ContextEngine
+
+# Local mode (zero config, SQLite backend)
+ctx = ContextEngine()
+
+# Platform mode (connects to Rotascale)
+ctx = ContextEngine(
+    api_key="rot_...",
+    base_url="https://api.rotascale.com",
+)
+
+# Ingest context
+result = ctx.ingest(
+    records=[
+        {"content": "User reported login issue", "title": "Support ticket #1234"},
+        {"content": "Auth service latency spike at 2pm UTC", "title": "Incident report"},
+    ],
+    source="helpdesk",
+    tags=["support", "auth"],
+    scope="team:support",
+)
+
+# Search
+results = ctx.search("login issues", top_k=5, mode="semantic")
+for hit in results:
+    print(f"{hit.score:.2f} — {hit.title}")
+
+# Subscribe to context updates
+ctx.on("context.created", filter={"tags": ["support"]}, callback=my_handler)
+```
+
+## Features
+
+- **Ingest**: Push data from any pipeline; we add the "C" (embeddings, entities, relationships)
+- **Search**: Semantic + keyword + hybrid search across all ingested context
+- **Subscribe**: Real-time context propagation via events
+- **ACLs**: Scope-based access control (global, team, agent, project, user)
+- **Pluggable backends**: SQLite (local), PostgreSQL (self-hosted), Rotascale Platform (managed)
+
+## Pipeline Adapters
+
+```python
+# Airflow
+from rotalabs_context.adapters import AirflowContextOperator
+
+# In your DAG
+ingest_task = AirflowContextOperator(
+    task_id="ingest_to_context",
+    source="airflow-etl",
+    tags=["daily-batch"],
+)
+```
+
+## License
+
+AGPL-3.0 — See [LICENSE](LICENSE) for details.

rotalabs_context-1.0.0/pyproject.toml

@@ -0,0 +1,86 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "rotalabs-context"
+version = "1.0.0"
+description = "Context intelligence for AI agents - Ingest, search, and subscribe to shared context across your AI systems"
+readme = "README.md"
+license = "AGPL-3.0-or-later"
+requires-python = ">=3.9"
+authors = [
+    { name = "Subhadip Mitra", email = "subhadip@rotalabs.ai" },
+    { name = "Rotalabs Research", email = "research@rotalabs.ai" },
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+keywords = [
+    "context",
+    "ai-agents",
+    "rag",
+    "embeddings",
+    "knowledge-graph",
+    "etl",
+    "context-engine",
+    "semantic-search",
+]
+dependencies = [
+    "pydantic>=2.0.0",
+]
+
+[project.optional-dependencies]
+local = [
+    "numpy>=1.24.0",
+    "sentence-transformers>=2.2.0",
+]
+platform = [
+    "httpx>=0.25.0",
+]
+airflow = [
+    "apache-airflow>=2.5.0",
+]
+telemetry = ["rotalabs[telemetry]>=1.0.0"]
+dev = [
+    "pytest>=7.4.0",
+    "pytest-cov>=4.1.0",
+    "pytest-asyncio>=0.21.0",
+    "ruff>=0.1.0",
+    "mypy>=1.5.0",
+]
+all = ["rotalabs-context[local,platform,telemetry]"]
+
+[project.urls]
+Homepage = "https://rotalabs.ai"
+Repository = "https://github.com/rotalabs/rotalabs-context"
+Documentation = "https://rotalabs.ai/docs/context"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/rotalabs_context"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E", "W", "F", "I", "B", "C4", "UP"]
+ignore = ["E501", "B008"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["rotalabs_context"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+addopts = "-v --cov=src/rotalabs_context --cov-report=term-missing"
+asyncio_mode = "auto"

rotalabs_context-1.0.0/src/rotalabs_context/__init__.py

@@ -0,0 +1,36 @@
+"""
+rotalabs-context: Context intelligence for AI agents.
+
+Provides tools to ingest, search, and subscribe to shared context
+across AI systems. Works standalone (local mode) or connected to
+the Rotascale platform (managed mode).
+
+Usage:
+    from rotalabs_context import ContextEngine
+
+    ctx = ContextEngine()
+    ctx.ingest(records=[{"content": "hello"}], source="test")
+    results = ctx.search("hello")
+"""
+
+from rotalabs_context._version import __version__
+from rotalabs_context.engine import ContextEngine
+from rotalabs_context.models import (
+    ContextEntry,
+    IngestResult,
+    SearchHit,
+    SearchResult,
+    Scope,
+    Sensitivity,
+)
+
+__all__ = [
+    "__version__",
+    "ContextEngine",
+    "ContextEntry",
+    "IngestResult",
+    "SearchHit",
+    "SearchResult",
+    "Scope",
+    "Sensitivity",
+]

rotalabs_context-1.0.0/src/rotalabs_context/_telemetry.py

@@ -0,0 +1,34 @@
+"""Telemetry integration for rotalabs-context.
+
+Safe wrapper around the rotalabs telemetry system.
+Opt-in only, gracefully degrades if not configured.
+"""
+
+from typing import Any
+
+try:
+    from rotalabs._telemetry import is_enabled, report_event
+except ImportError:
+    def report_event(*args: Any, **kwargs: Any) -> None:
+        pass
+
+    def is_enabled() -> bool:
+        return False
+
+
+def report_context_init(backend: str) -> None:
+    if not is_enabled():
+        return
+    report_event("context.engine.init", {"backend": backend})
+
+
+def report_context_ingest(source: str, count: int) -> None:
+    if not is_enabled():
+        return
+    report_event("context.ingest", {"source": source, "count": count})
+
+
+def report_context_search(mode: str, total: int) -> None:
+    if not is_enabled():
+        return
+    report_event("context.search", {"mode": mode, "total": total})

rotalabs_context-1.0.0/src/rotalabs_context/_version.py

@@ -0,0 +1 @@
+__version__ = "1.0.0"

rotalabs_context-1.0.0/src/rotalabs_context/adapters/__init__.py

@@ -0,0 +1 @@
+"""Pipeline adapters for integrating context into existing ETL workflows."""

rotalabs_context-1.0.0/src/rotalabs_context/adapters/airflow.py

@@ -0,0 +1,81 @@
+"""Apache Airflow adapter for rotalabs-context.
+
+Provides an Airflow operator that ingests context during DAG execution.
+
+Usage:
+    from rotalabs_context.adapters.airflow import AirflowContextOperator
+
+    ingest_task = AirflowContextOperator(
+        task_id="ingest_context",
+        source="my-etl-pipeline",
+        records_callable=lambda: [{"content": "data", "title": "record"}],
+        tags=["daily", "production"],
+    )
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable
+
+try:
+    from airflow.models import BaseOperator
+except ImportError:
+    # Stub for when airflow is not installed
+    class BaseOperator:  # type: ignore[no-redef]
+        def __init__(self, **kwargs: Any) -> None:
+            pass
+
+        def execute(self, context: Any) -> Any:
+            raise ImportError("apache-airflow is required. Install with: pip install rotalabs-context[airflow]")
+
+
+class AirflowContextOperator(BaseOperator):
+    """Airflow operator that ingests records into the context engine.
+
+    Parameters
+    ----------
+    source : str
+        Source identifier for the ingested context.
+    records_callable : callable
+        Function that returns a list of record dicts.
+    tags : list[str]
+        Tags to apply.
+    scope : str
+        Visibility scope.
+    api_key : str, optional
+        Rotascale API key. If not provided, uses ROTASCALE_API_KEY env var.
+    """
+
+    def __init__(
+        self,
+        source: str,
+        records_callable: Callable[..., list[dict[str, Any]]],
+        tags: list[str] | None = None,
+        scope: str = "global",
+        api_key: str | None = None,
+        base_url: str = "https://api.rotascale.com",
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(**kwargs)
+        self.source = source
+        self.records_callable = records_callable
+        self.tags = tags or []
+        self.scope = scope
+        self.api_key = api_key
+        self.base_url = base_url
+
+    def execute(self, context: Any) -> dict[str, Any]:
+        import os
+        from rotalabs_context import ContextEngine
+
+        api_key = self.api_key or os.environ.get("ROTASCALE_API_KEY")
+        ctx = ContextEngine(api_key=api_key, base_url=self.base_url)
+
+        records = self.records_callable()
+        result = ctx.ingest(
+            records=records,
+            source=self.source,
+            tags=self.tags,
+            scope=self.scope,
+        )
+        return result.model_dump()

rotalabs_context-1.0.0/src/rotalabs_context/backends/__init__.py

@@ -0,0 +1 @@
+"""Pluggable storage backends for rotalabs-context."""

rotalabs_context-1.0.0/src/rotalabs_context/backends/base.py

@@ -0,0 +1,34 @@
+"""Abstract backend interface."""
+
+from __future__ import annotations
+
+import abc
+
+from rotalabs_context.models import IngestRecord, IngestResult, SearchResult
+
+
+class Backend(abc.ABC):
+    """Abstract storage backend for the context engine."""
+
+    @abc.abstractmethod
+    def ingest(
+        self,
+        records: list[IngestRecord],
+        source: str,
+        tags: list[str],
+        scope: str,
+        sensitivity: str,
+        generate_embeddings: bool,
+        extract_entities: bool,
+    ) -> IngestResult:
+        ...
+
+    @abc.abstractmethod
+    def search(
+        self,
+        query: str,
+        top_k: int,
+        mode: str,
+        filters: dict,
+    ) -> SearchResult:
+        ...

rotalabs_context-1.0.0/src/rotalabs_context/backends/memory.py

@@ -0,0 +1,136 @@
+"""In-memory backend for local development and testing."""
+
+from __future__ import annotations
+
+import hashlib
+import re
+import time
+from datetime import datetime, timezone
+
+from rotalabs_context.backends.base import Backend
+from rotalabs_context.models import (
+    ContextEntry,
+    IngestRecord,
+    IngestResult,
+    SearchHit,
+    SearchResult,
+)
+
+
+class MemoryBackend(Backend):
+    """In-memory context store. Data is lost when process exits.
+
+    Good for testing, prototyping, and local development.
+    """
+
+    def __init__(self) -> None:
+        self._entries: list[ContextEntry] = []
+        self._counter = 0
+
+    def ingest(
+        self,
+        records: list[IngestRecord],
+        source: str,
+        tags: list[str],
+        scope: str,
+        sensitivity: str,
+        generate_embeddings: bool,
+        extract_entities: bool,
+    ) -> IngestResult:
+        entry_ids: list[str] = []
+        for record in records:
+            self._counter += 1
+            entry_id = f"ctx_{self._counter:06d}"
+            content_hash = hashlib.sha256(record.content.encode()).hexdigest()
+
+            entry = ContextEntry(
+                id=entry_id,
+                source=source,
+                source_id=record.source_id,
+                content_type=record.content_type,
+                title=record.title,
+                content=record.content,
+                content_hash=content_hash,
+                tags=tags,
+                scope=scope,
+                sensitivity=sensitivity,
+                metadata=record.metadata,
+                created_at=datetime.now(timezone.utc),
+            )
+            self._entries.append(entry)
+            entry_ids.append(entry_id)
+
+        return IngestResult(
+            entries_created=len(records),
+            embeddings_generated=0,  # No embeddings in memory mode
+            entities_extracted=0,
+            entry_ids=entry_ids,
+        )
+
+    def search(
+        self,
+        query: str,
+        top_k: int,
+        mode: str,
+        filters: dict,
+    ) -> SearchResult:
+        start = time.monotonic()
+        query_lower = query.lower()
+        query_tokens = set(re.findall(r"[a-z0-9]+", query_lower))
+
+        scored: list[SearchHit] = []
+        for entry in self._entries:
+            # Apply filters
+            if filters.get("tags"):
+                if not any(t in entry.tags for t in filters["tags"]):
+                    continue
+            if filters.get("sources"):
+                if entry.source not in filters["sources"]:
+                    continue
+            if filters.get("scopes"):
+                if entry.scope not in filters["scopes"]:
+                    continue
+
+            # Keyword matching
+            text = f"{entry.title or ''} {entry.content}".lower()
+            text_tokens = set(re.findall(r"[a-z0-9]+", text))
+
+            if not query_tokens:
+                continue
+
+            overlap = query_tokens & text_tokens
+            if not overlap:
+                continue
+
+            score = len(overlap) / len(query_tokens)
+
+            # Extract highlights
+            highlights: list[str] = []
+            for sentence in re.split(r"[.!?\n]+", entry.content):
+                sentence = sentence.strip()
+                if not sentence:
+                    continue
+                sent_tokens = set(re.findall(r"[a-z0-9]+", sentence.lower()))
+                if query_tokens & sent_tokens:
+                    highlights.append(sentence[:200])
+                    if len(highlights) >= 3:
+                        break
+
+            scored.append(SearchHit(
+                entry=entry,
+                score=round(score, 4),
+                highlights=highlights,
+                match_type="keyword",
+            ))
+
+        scored.sort(key=lambda x: x.score, reverse=True)
+        results = scored[:top_k]
+        took_ms = round((time.monotonic() - start) * 1000, 2)
+
+        return SearchResult(
+            query=query,
+            mode=mode,
+            results=results,
+            total=len(results),
+            took_ms=took_ms,
+        )