feat: add explorable and referenceable scaffolding (#108)

* feat: add explorable and referencable scaffolding

* fix: types

Author: mathislucka

pyproject.toml

@@ -12,6 +12,8 @@ dependencies = [
     "pyyaml",
     "numpy",
     "model2vec",
+    "glom",
+    "rich",
 ]
 
 [project.scripts]
@@ -102,8 +104,13 @@ convention = "pep257"
 strict = true
 
 [[tool.mypy.overrides]]
-module = ["haystack_integrations.*", "langfuse.*"]
+module = ["haystack_integrations.*", "langfuse.*", "glom"]
 ignore_missing_imports = true
 
+[[tool.mypy.overrides]]
+module = ["test.unit.tools.tokonomics.*"]
+disable_error_code = ["arg-type", "attr-defined", "operator", "misc", "type-arg", "no-any-return", "assignment"]
+# These tests intentionally test runtime decorator behavior that mypy cannot understand
+
 
 

src/deepset_mcp/tools/tokonomics/__init__.py

@@ -0,0 +1,72 @@
+"""
+Tokonomics: Explorable and Referenceable Tools for LLM Agents.
+
+=============================================================
+
+A library that provides token-efficient object exploration and reference
+passing capabilities for LLM agents.
+
+Key Features:
+- TTL-based object storage for temporary results
+- Rich object exploration with multiple rendering modes
+- Reference-based parameter passing (@obj_001.path.to.value)
+- Type-safe decorators that preserve function signatures
+- Configurable preview truncation and custom rendering callbacks
+
+Usage:
+------
+
+Basic explorable tool:
+
+    >>> from deepset_mcp.tools.tokonomics import explorable
+    >>>
+    >>> @explorable
+    >>> def get_data():
+    ...     return {"users": [{"name": "Alice", "age": 30}]}
+    >>>
+    >>> result = get_data()
+    >>> print(result)  # Shows rich preview
+    >>> result.obj_id  # "obj_001"
+    >>> result.value   # Original data
+
+Referenceable tool that accepts references:
+
+    >>> from deepset_mcp.tools.tokonomics import referenceable
+    >>>
+    >>> @referenceable
+    >>> def process_users(users: list) -> str:
+    ...     return f"Processed {len(users)} users"
+    >>>
+    >>> # Use with direct data
+    >>> process_users([{"name": "Bob"}])
+    >>>
+    >>> # Use with reference
+    >>> process_users("@obj_001.users")
+
+Exploration utilities:
+
+    >>> from deepset_mcp.tools.tokonomics import explore, search
+    >>>
+    >>> # Explore object structure
+    >>> explore("obj_001", mode="tree")
+    >>>
+    >>> # Search within objects
+    >>> search("obj_001", "Alice")
+"""
+
+from .decorators import explorable, referenceable
+from .explorer import RichExplorer
+from .object_store import Explorable, ObjectRef, ObjectStore
+
+__all__ = [
+    # Core classes
+    "Explorable",
+    "ObjectRef",
+    "ObjectStore",
+    "RichExplorer",
+    # Decorators
+    "explorable",
+    "referenceable",
+]
+
+__version__ = "0.1.0"