agentic-data 0.1.0__tar.gz

agentic_data-0.1.0/.gitignore

@@ -0,0 +1,47 @@
+# Rust
+target/
+**/*.rs.bk
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+*.orig
+
+# Python
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.eggs/
+*.whl
+venv/
+.venv/
+
+# Data files (test artifacts)
+*.adat
+*.tmp
+
+# LaTeX build artifacts
+paper/**/*.aux
+paper/**/*.bbl
+paper/**/*.blg
+paper/**/*.fdb_latexmk
+paper/**/*.fls
+paper/**/*.log
+paper/**/*.out
+paper/**/*.synctex.gz
+
+# Environment / secrets
+.env
+*.key
+
+# Internal planning (not published)
+planning-docs/

agentic_data-0.1.0/PKG-INFO

@@ -0,0 +1,32 @@
+Metadata-Version: 2.4
+Name: agentic-data
+Version: 0.1.0
+Summary: Universal data comprehension for AI agents
+Project-URL: Homepage, https://github.com/agentralabs/agentic-data
+Project-URL: Documentation, https://github.com/agentralabs/agentic-data/tree/main/docs
+Project-URL: Repository, https://github.com/agentralabs/agentic-data
+Author: Agentra Labs
+License-Expression: MIT
+Keywords: agents,ai,data,lineage,schema
+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: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# AgenticData Python SDK
+
+Pure-Python SDK that wraps the `adat` CLI binary.
+
+```bash
+pip install agentic-data
+```

agentic_data-0.1.0/README.md

@@ -0,0 +1,7 @@
+# AgenticData Python SDK
+
+Pure-Python SDK that wraps the `adat` CLI binary.
+
+```bash
+pip install agentic-data
+```

agentic_data-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "agentic-data"
+version = "0.1.0"
+description = "Universal data comprehension for AI agents"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Agentra Labs" },
+]
+keywords = ["ai", "agents", "data", "schema", "lineage"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+    "mypy>=1.10",
+]
+
+[project.urls]
+Homepage = "https://github.com/agentralabs/agentic-data"
+Documentation = "https://github.com/agentralabs/agentic-data/tree/main/docs"
+Repository = "https://github.com/agentralabs/agentic-data"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agentic_data"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true

agentic_data-0.1.0/src/agentic_data/__init__.py

@@ -0,0 +1,139 @@
+"""AgenticData — Universal data comprehension for AI agents.
+
+Pure-Python SDK that wraps the ``adat`` CLI binary via subprocess.
+Zero required dependencies; only stdlib: subprocess, json, pathlib, dataclasses.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import subprocess
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Optional
+
+__version__ = "0.1.0"
+
+logger = logging.getLogger(__name__)
+
+
+class DataError(Exception):
+    """Raised when an adat CLI command fails."""
+
+
+@dataclass
+class DataStore:
+    """Interface to an ``.adat`` data store file.
+
+    Parameters
+    ----------
+    path : str | Path
+        Path to the ``.adat`` file. Created automatically on first write
+        if it does not exist.
+    binary : str
+        Name or path of the ``adat`` CLI binary.
+    """
+
+    path: str | Path
+    binary: str = "adat"
+    _resolved_binary: Optional[str] = field(default=None, repr=False, init=False)
+
+    def __post_init__(self) -> None:
+        self.path = Path(self.path)
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _find_binary(self) -> str:
+        if self._resolved_binary is not None:
+            return self._resolved_binary
+
+        import shutil
+
+        found = shutil.which(self.binary)
+        if found is None:
+            raise DataError(
+                f"Cannot find '{self.binary}' on PATH. "
+                "Install AgenticData: curl -fsSL https://agentralabs.tech/install/data | bash"
+            )
+        self._resolved_binary = found
+        return found
+
+    def _run(self, *args: str, check: bool = True) -> str:
+        """Execute an adat CLI command and return stdout."""
+        cmd = [self._find_binary(), "--file", str(self.path), *args]
+        logger.debug("Running: %s", " ".join(cmd))
+        result = subprocess.run(cmd, capture_output=True, text=True)
+        if check and result.returncode != 0:
+            raise DataError(
+                f"adat command failed (exit {result.returncode}): {result.stderr.strip()}"
+            )
+        return result.stdout.strip()
+
+    def _run_json(self, *args: str) -> Any:
+        """Execute a command and parse JSON output."""
+        raw = self._run(*args, "--format", "json")
+        return json.loads(raw) if raw else {}
+
+    # ------------------------------------------------------------------
+    # Data operations
+    # ------------------------------------------------------------------
+
+    def detect_format(self, source: str) -> dict[str, Any]:
+        """Detect the format of a data source. Returns format metadata."""
+        return self._run_json("format", "detect", source)
+
+    def ingest(
+        self,
+        source: str,
+        *,
+        format: Optional[str] = None,
+        schema: Optional[str] = None,
+    ) -> str:
+        """Ingest data from a source. Returns the ingestion ID."""
+        args = ["ingest", source]
+        if format:
+            args.extend(["--format", format])
+        if schema:
+            args.extend(["--schema", schema])
+        return self._run(*args)
+
+    def query(self, expression: str, *, limit: Optional[int] = None) -> list[dict[str, Any]]:
+        """Query data with an expression. Returns matching records."""
+        args = ["query", expression, "--format", "json"]
+        if limit is not None:
+            args.extend(["--limit", str(limit)])
+        raw = self._run(*args)
+        return json.loads(raw) if raw else []
+
+    def quality_score(self, source: Optional[str] = None) -> dict[str, Any]:
+        """Compute data quality score. Returns quality metrics."""
+        args = ["quality", "score", "--format", "json"]
+        if source:
+            args.append(source)
+        raw = self._run(*args)
+        return json.loads(raw) if raw else {}
+
+    # ------------------------------------------------------------------
+    # Stats
+    # ------------------------------------------------------------------
+
+    def stats(self) -> dict[str, Any]:
+        """Get data store statistics."""
+        raw = self._run("stats", "--format", "json")
+        return json.loads(raw) if raw else {}
+
+    # ------------------------------------------------------------------
+    # File operations
+    # ------------------------------------------------------------------
+
+    def save(self) -> None:
+        """Explicit save (most operations auto-save)."""
+        pass
+
+    @property
+    def exists(self) -> bool:
+        """Whether the .adat file exists on disk."""
+        return self.path.exists()

agentic_data-0.1.0/tests/test_data.py

@@ -0,0 +1,310 @@
+"""Comprehensive tests for AgenticData Python SDK."""
+from __future__ import annotations
+
+import json
+import subprocess
+from pathlib import Path, PurePosixPath
+from unittest.mock import patch, MagicMock
+
+import pytest
+
+from agentic_data import DataStore, DataError, __version__
+
+
+# ---------------------------------------------------------------------------
+# 1. Package Metadata
+# ---------------------------------------------------------------------------
+
+
+class TestPackageMetadata:
+    def test_version_exists(self) -> None:
+        assert __version__ is not None
+        assert isinstance(__version__, str)
+        assert len(__version__) > 0
+
+    def test_version_semver(self) -> None:
+        parts = __version__.split(".")
+        assert len(parts) == 3
+        assert all(p.isdigit() for p in parts)
+
+    def test_version_is_010(self) -> None:
+        assert __version__ == "0.1.0"
+
+    def test_import_main_class(self) -> None:
+        assert DataStore is not None
+
+    def test_import_error_class(self) -> None:
+        assert DataError is not None
+        assert issubclass(DataError, Exception)
+
+    def test_main_class_has_docstring(self) -> None:
+        assert DataStore.__doc__ is not None
+        assert len(DataStore.__doc__) > 10
+
+
+# ---------------------------------------------------------------------------
+# 2. Initialization
+# ---------------------------------------------------------------------------
+
+
+class TestInit:
+    def test_create_with_string_path(self, tmp_path: Path) -> None:
+        path = str(tmp_path / "test.adat")
+        obj = DataStore(path)
+        assert str(obj.path) == path
+
+    def test_create_with_path_object(self, tmp_path: Path) -> None:
+        path = tmp_path / "test.adat"
+        obj = DataStore(path)
+        assert obj.path == path
+
+    def test_create_with_pure_posix_path(self) -> None:
+        obj = DataStore(PurePosixPath("/tmp/test.adat"))
+        assert "test.adat" in str(obj.path)
+
+    def test_path_converted_to_path_object(self, tmp_path: Path) -> None:
+        path = str(tmp_path / "test.adat")
+        obj = DataStore(path)
+        assert isinstance(obj.path, Path)
+
+    def test_custom_binary_name(self, tmp_path: Path) -> None:
+        obj = DataStore(str(tmp_path / "test.adat"), binary="custom-bin")
+        assert obj.binary == "custom-bin"
+
+    def test_default_binary_name(self, tmp_path: Path) -> None:
+        obj = DataStore(str(tmp_path / "test.adat"))
+        assert obj.binary == "adat"
+
+    def test_exists_false_for_new(self, tmp_path: Path) -> None:
+        obj = DataStore(str(tmp_path / "nonexistent.adat"))
+        assert not obj.exists
+
+    def test_exists_true_when_file_present(self, tmp_path: Path) -> None:
+        path = tmp_path / "exists.adat"
+        path.touch()
+        obj = DataStore(str(path))
+        assert obj.exists
+
+    def test_save_is_noop(self, tmp_path: Path) -> None:
+        obj = DataStore(str(tmp_path / "test.adat"))
+        obj.save()  # should not raise
+
+    def test_repr_does_not_crash(self, tmp_path: Path) -> None:
+        obj = DataStore(str(tmp_path / "test.adat"))
+        r = repr(obj)
+        assert isinstance(r, str)
+
+
+# ---------------------------------------------------------------------------
+# 3. Binary Resolution
+# ---------------------------------------------------------------------------
+
+
+class TestBinaryResolution:
+    def test_missing_binary_raises(self, tmp_path: Path) -> None:
+        obj = DataStore(str(tmp_path / "t.adat"), binary="nonexistent-xyz-999")
+        with pytest.raises(DataError):
+            obj._find_binary()
+
+    def test_error_contains_binary_name(self, tmp_path: Path) -> None:
+        obj = DataStore(str(tmp_path / "t.adat"), binary="nonexistent-xyz-999")
+        with pytest.raises(DataError, match="nonexistent-xyz-999"):
+            obj._find_binary()
+
+    def test_error_contains_install_hint(self, tmp_path: Path) -> None:
+        obj = DataStore(str(tmp_path / "t.adat"), binary="nonexistent-xyz-999")
+        with pytest.raises(DataError, match="Install"):
+            obj._find_binary()
+
+    def test_caches_result(self, tmp_path: Path) -> None:
+        obj = DataStore(str(tmp_path / "t.adat"))
+        obj._resolved_binary = "/fake/path/adat"
+        assert obj._find_binary() == "/fake/path/adat"
+
+    def test_cache_persists_across_calls(self, tmp_path: Path) -> None:
+        obj = DataStore(str(tmp_path / "t.adat"))
+        obj._resolved_binary = "/cached/bin"
+        assert obj._find_binary() == "/cached/bin"
+        assert obj._find_binary() == "/cached/bin"
+
+
+# ---------------------------------------------------------------------------
+# 4. Subprocess Execution
+# ---------------------------------------------------------------------------
+
+
+class TestSubprocessExecution:
+    def test_run_calls_subprocess(self, tmp_path: Path) -> None:
+        obj = DataStore(str(tmp_path / "t.adat"))
+        obj._resolved_binary = "/usr/bin/echo"
+        with patch("subprocess.run") as mock_run:
+            mock_run.return_value = MagicMock(
+                returncode=0, stdout="ok\n", stderr=""
+            )
+            result = obj._run("arg1", "arg2")
+            assert mock_run.called
+            cmd = mock_run.call_args[0][0]
+            assert cmd[0] == "/usr/bin/echo"
+            assert "arg1" in cmd
+            assert "arg2" in cmd
+
+    def test_run_includes_file_flag(self, tmp_path: Path) -> None:
+        obj = DataStore(str(tmp_path / "t.adat"))
+        obj._resolved_binary = "/usr/bin/echo"
+        with patch("subprocess.run") as mock_run:
+            mock_run.return_value = MagicMock(
+                returncode=0, stdout="ok\n", stderr=""
+            )
+            obj._run("test")
+            cmd = mock_run.call_args[0][0]
+            assert "--file" in cmd
+            assert str(tmp_path / "t.adat") in cmd
+
+    def test_run_raises_on_nonzero_exit(self, tmp_path: Path) -> None:
+        obj = DataStore(str(tmp_path / "t.adat"))
+        obj._resolved_binary = "/bin/false"
+        with patch("subprocess.run") as mock_run:
+            mock_run.return_value = MagicMock(
+                returncode=1, stdout="", stderr="error happened"
+            )
+            with pytest.raises(DataError, match="error happened"):
+                obj._run("fail")
+
+    def test_run_returns_stripped_stdout(self, tmp_path: Path) -> None:
+        obj = DataStore(str(tmp_path / "t.adat"))
+        obj._resolved_binary = "/usr/bin/echo"
+        with patch("subprocess.run") as mock_run:
+            mock_run.return_value = MagicMock(
+                returncode=0, stdout="  hello world  \n", stderr=""
+            )
+            result = obj._run("test")
+            assert result == "hello world"
+
+    def test_run_json_parses_output(self, tmp_path: Path) -> None:
+        obj = DataStore(str(tmp_path / "t.adat"))
+        obj._resolved_binary = "/usr/bin/echo"
+        with patch("subprocess.run") as mock_run:
+            mock_run.return_value = MagicMock(
+                returncode=0, stdout='{"key": "value"}\n', stderr=""
+            )
+            result = obj._run_json("test")
+            assert result == {"key": "value"}
+
+    def test_run_json_raises_on_invalid_json(self, tmp_path: Path) -> None:
+        obj = DataStore(str(tmp_path / "t.adat"))
+        obj._resolved_binary = "/usr/bin/echo"
+        with patch("subprocess.run") as mock_run:
+            mock_run.return_value = MagicMock(
+                returncode=0, stdout="not json at all", stderr=""
+            )
+            with pytest.raises((json.JSONDecodeError, DataError)):
+                obj._run_json("test")
+
+    def test_run_json_returns_empty_dict_on_empty_output(self, tmp_path: Path) -> None:
+        obj = DataStore(str(tmp_path / "t.adat"))
+        obj._resolved_binary = "/usr/bin/echo"
+        with patch("subprocess.run") as mock_run:
+            mock_run.return_value = MagicMock(
+                returncode=0, stdout="", stderr=""
+            )
+            result = obj._run_json("test")
+            assert result == {}
+
+
+# ---------------------------------------------------------------------------
+# 5. Edge Cases
+# ---------------------------------------------------------------------------
+
+
+class TestEdgeCases:
+    def test_empty_path(self) -> None:
+        obj = DataStore("")
+        assert isinstance(obj.path, Path)
+
+    def test_path_with_spaces(self, tmp_path: Path) -> None:
+        path = tmp_path / "path with spaces" / "test.adat"
+        obj = DataStore(str(path))
+        assert "spaces" in str(obj.path)
+
+    def test_path_with_unicode(self, tmp_path: Path) -> None:
+        path = tmp_path / "donnees" / "test.adat"
+        obj = DataStore(str(path))
+        assert "donnees" in str(obj.path)
+
+    def test_very_long_path(self, tmp_path: Path) -> None:
+        long_name = "a" * 200
+        path = tmp_path / long_name / "test.adat"
+        obj = DataStore(str(path))
+        assert len(str(obj.path)) > 200
+
+    def test_save_idempotent(self, tmp_path: Path) -> None:
+        obj = DataStore(str(tmp_path / "t.adat"))
+        obj.save()
+        obj.save()
+        obj.save()
+
+    def test_multiple_instances_independent(self, tmp_path: Path) -> None:
+        a = DataStore(str(tmp_path / "a.adat"))
+        b = DataStore(str(tmp_path / "b.adat"))
+        assert a.path != b.path
+        a._resolved_binary = "/path/a"
+        assert b._resolved_binary is None
+
+    def test_dot_in_directory_name(self, tmp_path: Path) -> None:
+        path = tmp_path / "v1.0.0" / "test.adat"
+        obj = DataStore(str(path))
+        assert "v1.0.0" in str(obj.path)
+
+
+# ---------------------------------------------------------------------------
+# 6. Error Handling
+# ---------------------------------------------------------------------------
+
+
+class TestErrorHandling:
+    def test_error_is_exception(self) -> None:
+        assert issubclass(DataError, Exception)
+
+    def test_error_stores_message(self) -> None:
+        err = DataError("test message")
+        assert "test message" in str(err)
+
+    def test_error_caught_as_exception(self) -> None:
+        with pytest.raises(Exception):
+            raise DataError("boom")
+
+    def test_error_caught_specifically(self) -> None:
+        try:
+            raise DataError("specific")
+        except DataError as e:
+            assert "specific" in str(e)
+
+    def test_error_repr(self) -> None:
+        err = DataError("repr test")
+        assert repr(err) is not None
+
+
+# ---------------------------------------------------------------------------
+# 7. Stress Tests
+# ---------------------------------------------------------------------------
+
+
+class TestStress:
+    def test_create_1000_instances(self, tmp_path: Path) -> None:
+        instances = [
+            DataStore(str(tmp_path / f"test_{i}.adat"))
+            for i in range(1000)
+        ]
+        assert len(instances) == 1000
+        assert instances[0].path != instances[999].path
+
+    def test_find_binary_1000_cached(self, tmp_path: Path) -> None:
+        obj = DataStore(str(tmp_path / "t.adat"))
+        obj._resolved_binary = "/cached/bin"
+        for _ in range(1000):
+            assert obj._find_binary() == "/cached/bin"
+
+    def test_save_100_times(self, tmp_path: Path) -> None:
+        obj = DataStore(str(tmp_path / "t.adat"))
+        for _ in range(100):
+            obj.save()