convertcom · usmanabbas7 · Apr 7, 2026 · Apr 7, 2026 · gemini-code-assist · Apr 7, 2026
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1,4 @@
+.pytest_cache/
+.venv/
+__pycache__/
+dist/
diff --git a/.python-version b/.python-version
@@ -0,0 +1 @@
+3.13
diff --git a/README.md b/README.md
@@ -0,0 +1,25 @@
+## convert-python-sdk
+
+This repository currently contains the Story 1.1 scaffold for Convert's Python SDK.
+
+Canonical package decisions frozen in this story:
+
+- Distribution name: `convert-python-sdk`
+- Import package: `convert_sdk`
+- Stable public imports: `Core`, `Context`, and `__version__`
+
+The scaffold is intentionally minimal. Feature initialization, configuration loading, local evaluation, and tracking behavior will land in later stories.
+
+### Local Development
+
+```bash
+UV_CACHE_DIR=/tmp/uv-cache uv sync --group dev
+UV_CACHE_DIR=/tmp/uv-cache uv run pytest
+UV_CACHE_DIR=/tmp/uv-cache uv build
-UV_CACHE_DIR=/tmp/uv-cache uv sync --group dev
-UV_CACHE_DIR=/tmp/uv-cache uv run pytest
-UV_CACHE_DIR=/tmp/uv-cache uv build
+uv sync --group dev
+uv run pytest
+uv build
-UV_CACHE_DIR=/tmp/uv-cache uv sync --group dev
-UV_CACHE_DIR=/tmp/uv-cache uv run pytest
-UV_CACHE_DIR=/tmp/uv-cache uv build
+uv sync --group dev
+uv run pytest
+uv build
+```
+
+### Public Import Boundary
+
+```python
+from convert_sdk import Context, Core, __version__
+```
diff --git a/pyproject.toml b/pyproject.toml
@@ -0,0 +1,36 @@
+[project]
+name = "convert-python-sdk"
+version = "0.1.0"
-version = "0.1.0"
+dynamic = ["version"]
-version = "0.1.0"
+dynamic = ["version"]
+description = "Framework-agnostic Python SDK scaffold for Convert."
+readme = "README.md"
+authors = [
+    { name = "Usman Abbas", email = "usman.abbas7@gmail.com" }
+]
+requires-python = ">=3.9"
+dependencies = []
+
+[dependency-groups]
+dev = [
+    "pytest>=8.4,<9",
+]
+
+[build-system]
+requires = ["hatchling>=1.29,<2"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/convert_sdk"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"src/convert_sdk/py.typed" = "convert_sdk/py.typed"
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "README.md",
+    "src/convert_sdk/**/*.py",
+    "src/convert_sdk/py.typed",
+    "tests/**/*.py",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
-[tool.pytest.ini_options]
-testpaths = ["tests"]
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.hatch.version]
+path = "src/convert_sdk/version.py"
-[tool.pytest.ini_options]
-testpaths = ["tests"]
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.hatch.version]
+path = "src/convert_sdk/version.py"
diff --git a/src/convert_sdk/__init__.py b/src/convert_sdk/__init__.py
@@ -0,0 +1,7 @@
+"""Stable public import boundary for the Convert Python SDK."""
+
+from .context import Context
+from .core import Core
+from .version import __version__
+
+__all__ = ["Context", "Core", "__version__"]
diff --git a/src/convert_sdk/context.py b/src/convert_sdk/context.py
@@ -0,0 +1,8 @@
+"""Per-visitor context placeholder reserved for later stories."""
+
+
+class Context:
+    """Stable root export for visitor-scoped SDK behavior."""
+
+    def __repr__(self) -> str:
+        return "Context()"
diff --git a/src/convert_sdk/core.py b/src/convert_sdk/core.py
@@ -0,0 +1,8 @@
+"""Public SDK entry point placeholder for future initialization work."""
+
+
+class Core:
+    """Stable root export reserved for SDK initialization and context creation."""
+
+    def __repr__(self) -> str:
+        return "Core()"
diff --git a/src/convert_sdk/py.typed b/src/convert_sdk/py.typed
@@ -0,0 +1 @@
+
diff --git a/src/convert_sdk/version.py b/src/convert_sdk/version.py
@@ -0,0 +1,3 @@
+"""Version metadata for the public SDK package."""
+
+__version__ = "0.1.0"
diff --git a/tests/test_packaging.py b/tests/test_packaging.py
@@ -0,0 +1,20 @@
+from importlib.metadata import distribution
+from pathlib import Path
+
+
+PROJECT_ROOT = Path(__file__).resolve().parents[1]
+
+
+def test_distribution_metadata_matches_story_contract() -> None:
+    dist = distribution("convert-python-sdk")
+
+    assert dist.metadata["Name"] == "convert-python-sdk"
+    assert dist.metadata["Requires-Python"] == ">=3.9"
+    assert dist.requires in (None, [])
+
+
+def test_pyproject_freezes_convert_sdk_package_boundary() -> None:
+    pyproject = (PROJECT_ROOT / "pyproject.toml").read_text(encoding="utf-8")
+
+    assert 'packages = ["src/convert_sdk"]' in pyproject
+    assert '"src/convert_sdk/py.typed" = "convert_sdk/py.typed"' in pyproject
diff --git a/tests/test_public_api.py b/tests/test_public_api.py
@@ -0,0 +1,14 @@
+from importlib import resources
+
+from convert_sdk import Context, Core, __version__
+
+
+def test_public_import_boundary_is_stable() -> None:
+    assert Core.__module__ == "convert_sdk.core"
+    assert Context.__module__ == "convert_sdk.context"
+    assert __version__ == "0.1.0"
-from importlib import resources
-
-from convert_sdk import Context, Core, __version__
-
-
-def test_public_import_boundary_is_stable() -> None:
-    assert Core.__module__ == "convert_sdk.core"
-    assert Context.__module__ == "convert_sdk.context"
-    assert __version__ == "0.1.0"
+from importlib import metadata, resources
+
+from convert_sdk import Context, Core, __version__
+
+
+def test_public_import_boundary_is_stable() -> None:
+    assert Core.__module__ == "convert_sdk.core"
+    assert Context.__module__ == "convert_sdk.context"
+    assert __version__ == metadata.version("convert-python-sdk")
-from importlib import resources
-
-from convert_sdk import Context, Core, __version__
-
-
-def test_public_import_boundary_is_stable() -> None:
-    assert Core.__module__ == "convert_sdk.core"
-    assert Context.__module__ == "convert_sdk.context"
-    assert __version__ == "0.1.0"
+from importlib import metadata, resources
+
+from convert_sdk import Context, Core, __version__
+
+
+def test_public_import_boundary_is_stable() -> None:
+    assert Core.__module__ == "convert_sdk.core"
+    assert Context.__module__ == "convert_sdk.context"
+    assert __version__ == metadata.version("convert-python-sdk")
+
+
+def test_py_typed_marker_is_available() -> None:
+    marker = resources.files("convert_sdk").joinpath("py.typed")
+    assert marker.is_file()
diff --git a/uv.lock b/uv.lock
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		"""Version metadata for the public SDK package."""

		__version__ = "0.1.0"