sudhanva 0.1.0__tar.gz

sudhanva-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Sudhanva Narayana
+
+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.
+

sudhanva-0.1.0/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: sudhanva
+Version: 0.1.0
+Summary: Minimal Python client for the public sudhanva.me API.
+Author-email: Sudhanva Narayana <nsudhanva@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://sudhanva.me
+Project-URL: Documentation, https://sudhanva.me/developers/sdks/
+Project-URL: Source, https://github.com/nsudhanva/sudhanva-python
+Project-URL: Issues, https://github.com/nsudhanva/sudhanva-python/issues
+Project-URL: OpenAPI, https://sudhanva.me/openapi.json
+Keywords: sudhanva,api,sdk,agents,machine-learning
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# sudhanva for Python
+
+Minimal, dependency-free Python client for the public
+[sudhanva.me API](https://sudhanva.me/openapi.json). It retrieves published profile and article
+metadata, performs bounded batch reads, searches the published site, and creates or polls temporary
+profile-insight jobs.
+
+The API is public and requires no credentials. Do not send private data.
+
+## Install
+
+```bash
+python -m pip install sudhanva
+```
+
+## Use
+
+```python
+from sudhanva import Client
+
+client = Client()
+
+profile = client.profile()
+posts = client.posts(limit=5, tag="kubernetes")
+article = client.post("making-your-site-agent-friendly")
+
+job = client.create_profile_insight(
+    audience="hiring-manager",
+    focus=["production-ml", "inference"],
+    idempotency_key="my-workflow-2026-08-23",
+)
+result = client.wait_for_profile_insight(job["job_id"])
+```
+
+All methods return decoded JSON dictionaries. Non-success responses raise `sudhanva.APIError` with
+`status`, `code`, `message`, and the decoded response body.
+
+## API coverage
+
+- `profile()`
+- `posts()` and `post()`
+- `batch()`
+- `create_profile_insight()`, `profile_insight()`, and `wait_for_profile_insight()`
+- `ask()` for NLWeb conversational search
+
+The client follows the stable `/api/v1` contract. See the
+[developer documentation](https://sudhanva.me/developers/sdks/) and
+[versioning policy](https://sudhanva.me/developers/versioning/).
+
+## Development
+
+```bash
+python -m pip install -e .
+python -m unittest discover -s tests -v
+python -m build
+```
+
+The test suite uses an injected transport and never calls production.
+
+## License
+
+MIT
+

sudhanva-0.1.0/README.md

@@ -0,0 +1,63 @@
+# sudhanva for Python
+
+Minimal, dependency-free Python client for the public
+[sudhanva.me API](https://sudhanva.me/openapi.json). It retrieves published profile and article
+metadata, performs bounded batch reads, searches the published site, and creates or polls temporary
+profile-insight jobs.
+
+The API is public and requires no credentials. Do not send private data.
+
+## Install
+
+```bash
+python -m pip install sudhanva
+```
+
+## Use
+
+```python
+from sudhanva import Client
+
+client = Client()
+
+profile = client.profile()
+posts = client.posts(limit=5, tag="kubernetes")
+article = client.post("making-your-site-agent-friendly")
+
+job = client.create_profile_insight(
+    audience="hiring-manager",
+    focus=["production-ml", "inference"],
+    idempotency_key="my-workflow-2026-08-23",
+)
+result = client.wait_for_profile_insight(job["job_id"])
+```
+
+All methods return decoded JSON dictionaries. Non-success responses raise `sudhanva.APIError` with
+`status`, `code`, `message`, and the decoded response body.
+
+## API coverage
+
+- `profile()`
+- `posts()` and `post()`
+- `batch()`
+- `create_profile_insight()`, `profile_insight()`, and `wait_for_profile_insight()`
+- `ask()` for NLWeb conversational search
+
+The client follows the stable `/api/v1` contract. See the
+[developer documentation](https://sudhanva.me/developers/sdks/) and
+[versioning policy](https://sudhanva.me/developers/versioning/).
+
+## Development
+
+```bash
+python -m pip install -e .
+python -m unittest discover -s tests -v
+python -m build
+```
+
+The test suite uses an injected transport and never calls production.
+
+## License
+
+MIT
+

sudhanva-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sudhanva"
+version = "0.1.0"
+description = "Minimal Python client for the public sudhanva.me API."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [{ name = "Sudhanva Narayana", email = "nsudhanva@gmail.com" }]
+keywords = ["sudhanva", "api", "sdk", "agents", "machine-learning"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Software Development :: Libraries",
+  "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://sudhanva.me"
+Documentation = "https://sudhanva.me/developers/sdks/"
+Source = "https://github.com/nsudhanva/sudhanva-python"
+Issues = "https://github.com/nsudhanva/sudhanva-python/issues"
+OpenAPI = "https://sudhanva.me/openapi.json"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+sudhanva = ["py.typed"]
+

sudhanva-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sudhanva-0.1.0/src/sudhanva/__init__.py

@@ -0,0 +1,7 @@
+"""Python client for the public sudhanva.me API."""
+
+from .client import APIError, Client
+
+__all__ = ["APIError", "Client"]
+__version__ = "0.1.0"
+

sudhanva-0.1.0/src/sudhanva/client.py

@@ -0,0 +1,204 @@
+"""Dependency-free client for the public sudhanva.me API."""
+
+from __future__ import annotations
+
+import json
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass
+from typing import Any, Callable, Mapping, Optional, Sequence
+
+DEFAULT_BASE_URL = "https://sudhanva.me/api/v1"
+USER_AGENT = "sudhanva-python/0.1.0"
+
+
+@dataclass(frozen=True)
+class Response:
+    status: int
+    headers: Mapping[str, str]
+    body: bytes
+
+
+Transport = Callable[[str, str, Mapping[str, str], Optional[bytes], float], Response]
+
+
+class APIError(RuntimeError):
+    """An error response returned by the sudhanva.me API."""
+
+    def __init__(self, status: int, code: str, message: str, body: Any) -> None:
+        super().__init__(f"{status} {code}: {message}")
+        self.status = status
+        self.code = code
+        self.message = message
+        self.body = body
+
+
+class Client:
+    """Small synchronous client for every stable public API operation."""
+
+    def __init__(
+        self,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 10.0,
+        transport: Optional[Transport] = None,
+    ) -> None:
+        if timeout <= 0:
+            raise ValueError("timeout must be positive")
+        self.base_url = base_url.rstrip("/")
+        parsed = urllib.parse.urlsplit(self.base_url)
+        if parsed.scheme not in {"http", "https"} or not parsed.netloc:
+            raise ValueError("base_url must be an absolute HTTP(S) URL")
+        self.site_url = f"{parsed.scheme}://{parsed.netloc}"
+        self.timeout = timeout
+        self._transport = transport or self._default_transport
+
+    def profile(self, *, locale: str = "en") -> dict[str, Any]:
+        return self._request("GET", "/profile", query={"locale": locale})
+
+    def posts(
+        self,
+        *,
+        limit: int = 20,
+        tag: Optional[str] = None,
+        cursor: Optional[str] = None,
+    ) -> dict[str, Any]:
+        if not 1 <= limit <= 100:
+            raise ValueError("limit must be between 1 and 100")
+        return self._request(
+            "GET",
+            "/posts",
+            query={"limit": limit, "tag": tag, "cursor": cursor},
+        )
+
+    def post(self, slug: str) -> dict[str, Any]:
+        if not slug:
+            raise ValueError("slug is required")
+        return self._request("GET", f"/posts/{urllib.parse.quote(slug, safe='')}")
+
+    def batch(self, operations: Sequence[Mapping[str, Any]]) -> dict[str, Any]:
+        if not 1 <= len(operations) <= 20:
+            raise ValueError("operations must contain between 1 and 20 items")
+        return self._request("POST", "/batch", json_body={"operations": list(operations)})
+
+    def create_profile_insight(
+        self,
+        *,
+        audience: str,
+        idempotency_key: str,
+        focus: Optional[Sequence[str]] = None,
+    ) -> dict[str, Any]:
+        if not idempotency_key:
+            raise ValueError("idempotency_key is required")
+        body: dict[str, Any] = {"audience": audience}
+        if focus is not None:
+            body["focus"] = list(focus)
+        return self._request(
+            "POST",
+            "/profile-insights",
+            headers={"Idempotency-Key": idempotency_key},
+            json_body=body,
+        )
+
+    def profile_insight(self, job_id: str) -> dict[str, Any]:
+        if not job_id:
+            raise ValueError("job_id is required")
+        return self._request(
+            "GET", f"/profile-insights/{urllib.parse.quote(job_id, safe='')}"
+        )
+
+    def wait_for_profile_insight(
+        self,
+        job_id: str,
+        *,
+        timeout: float = 30.0,
+        poll_interval: float = 1.0,
+    ) -> dict[str, Any]:
+        if timeout <= 0 or poll_interval < 0:
+            raise ValueError("timeout must be positive and poll_interval cannot be negative")
+        deadline = time.monotonic() + timeout
+        while True:
+            job = self.profile_insight(job_id)
+            if job.get("status") in {"succeeded", "failed"}:
+                return job
+            if time.monotonic() >= deadline:
+                raise TimeoutError(f"profile insight {job_id} did not finish within {timeout}s")
+            time.sleep(poll_interval)
+
+    def ask(
+        self,
+        text: str,
+        *,
+        limit: int = 10,
+        mode: str = "list",
+    ) -> dict[str, Any]:
+        if not text:
+            raise ValueError("text is required")
+        if not 1 <= limit <= 20:
+            raise ValueError("limit must be between 1 and 20")
+        return self._request(
+            "POST",
+            "/ask",
+            absolute_base=self.site_url,
+            json_body={
+                "query": {"text": text, "site": self.site_url, "limit": limit},
+                "prefer": {"streaming": False, "response_format": "conversational_search", "mode": mode},
+                "meta": {"version": "0.55"},
+            },
+        )
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: Optional[Mapping[str, Any]] = None,
+        headers: Optional[Mapping[str, str]] = None,
+        json_body: Optional[Mapping[str, Any]] = None,
+        absolute_base: Optional[str] = None,
+    ) -> dict[str, Any]:
+        pairs = [] if query is None else [(key, value) for key, value in query.items() if value is not None]
+        query_string = urllib.parse.urlencode(pairs)
+        url = f"{(absolute_base or self.base_url).rstrip('/')}/{path.lstrip('/')}"
+        if query_string:
+            url = f"{url}?{query_string}"
+
+        request_headers = {"Accept": "application/json", "User-Agent": USER_AGENT}
+        request_headers.update(headers or {})
+        body = None
+        if json_body is not None:
+            body = json.dumps(json_body, separators=(",", ":")).encode("utf-8")
+            request_headers["Content-Type"] = "application/json"
+
+        response = self._transport(method, url, request_headers, body, self.timeout)
+        try:
+            payload = json.loads(response.body.decode("utf-8")) if response.body else {}
+        except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+            raise APIError(response.status, "invalid_response", "API returned invalid JSON", None) from exc
+
+        if not 200 <= response.status < 300:
+            error = payload.get("error", payload) if isinstance(payload, dict) else {}
+            code = str(error.get("code", payload.get("code", "api_error")))
+            message = str(error.get("message", payload.get("message", "Request failed")))
+            raise APIError(response.status, code, message, payload)
+        if not isinstance(payload, dict):
+            raise APIError(response.status, "invalid_response", "API returned a non-object response", payload)
+        return payload
+
+    @staticmethod
+    def _default_transport(
+        method: str,
+        url: str,
+        headers: Mapping[str, str],
+        body: Optional[bytes],
+        timeout: float,
+    ) -> Response:
+        request = urllib.request.Request(url, data=body, headers=dict(headers), method=method)
+        try:
+            with urllib.request.urlopen(request, timeout=timeout) as result:
+                return Response(result.status, dict(result.headers.items()), result.read())
+        except urllib.error.HTTPError as error:
+            return Response(error.code, dict(error.headers.items()), error.read())
+

sudhanva-0.1.0/src/sudhanva/py.typed

@@ -0,0 +1 @@
+

sudhanva-0.1.0/src/sudhanva.egg-info/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: sudhanva
+Version: 0.1.0
+Summary: Minimal Python client for the public sudhanva.me API.
+Author-email: Sudhanva Narayana <nsudhanva@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://sudhanva.me
+Project-URL: Documentation, https://sudhanva.me/developers/sdks/
+Project-URL: Source, https://github.com/nsudhanva/sudhanva-python
+Project-URL: Issues, https://github.com/nsudhanva/sudhanva-python/issues
+Project-URL: OpenAPI, https://sudhanva.me/openapi.json
+Keywords: sudhanva,api,sdk,agents,machine-learning
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# sudhanva for Python
+
+Minimal, dependency-free Python client for the public
+[sudhanva.me API](https://sudhanva.me/openapi.json). It retrieves published profile and article
+metadata, performs bounded batch reads, searches the published site, and creates or polls temporary
+profile-insight jobs.
+
+The API is public and requires no credentials. Do not send private data.
+
+## Install
+
+```bash
+python -m pip install sudhanva
+```
+
+## Use
+
+```python
+from sudhanva import Client
+
+client = Client()
+
+profile = client.profile()
+posts = client.posts(limit=5, tag="kubernetes")
+article = client.post("making-your-site-agent-friendly")
+
+job = client.create_profile_insight(
+    audience="hiring-manager",
+    focus=["production-ml", "inference"],
+    idempotency_key="my-workflow-2026-08-23",
+)
+result = client.wait_for_profile_insight(job["job_id"])
+```
+
+All methods return decoded JSON dictionaries. Non-success responses raise `sudhanva.APIError` with
+`status`, `code`, `message`, and the decoded response body.
+
+## API coverage
+
+- `profile()`
+- `posts()` and `post()`
+- `batch()`
+- `create_profile_insight()`, `profile_insight()`, and `wait_for_profile_insight()`
+- `ask()` for NLWeb conversational search
+
+The client follows the stable `/api/v1` contract. See the
+[developer documentation](https://sudhanva.me/developers/sdks/) and
+[versioning policy](https://sudhanva.me/developers/versioning/).
+
+## Development
+
+```bash
+python -m pip install -e .
+python -m unittest discover -s tests -v
+python -m build
+```
+
+The test suite uses an injected transport and never calls production.
+
+## License
+
+MIT
+

sudhanva-0.1.0/src/sudhanva.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+src/sudhanva/__init__.py
+src/sudhanva/client.py
+src/sudhanva/py.typed
+src/sudhanva.egg-info/PKG-INFO
+src/sudhanva.egg-info/SOURCES.txt
+src/sudhanva.egg-info/dependency_links.txt
+src/sudhanva.egg-info/top_level.txt
+tests/test_client.py

sudhanva-0.1.0/src/sudhanva.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

sudhanva-0.1.0/src/sudhanva.egg-info/top_level.txt

@@ -0,0 +1 @@
+sudhanva

sudhanva-0.1.0/tests/test_client.py

@@ -0,0 +1,92 @@
+import json
+import unittest
+
+from sudhanva import APIError, Client
+from sudhanva.client import Response
+
+
+class FakeTransport:
+    def __init__(self, responses):
+        self.responses = list(responses)
+        self.requests = []
+
+    def __call__(self, method, url, headers, body, timeout):
+        self.requests.append((method, url, headers, body, timeout))
+        return self.responses.pop(0)
+
+
+def response(status, payload):
+    return Response(status, {"Content-Type": "application/json"}, json.dumps(payload).encode())
+
+
+class ClientTest(unittest.TestCase):
+    def test_posts_encodes_filters_and_identifies_client(self):
+        transport = FakeTransport([response(200, {"posts": []})])
+        client = Client(base_url="https://example.test/api/v1", transport=transport)
+
+        self.assertEqual(client.posts(limit=5, tag="machine-learning"), {"posts": []})
+
+        method, url, headers, body, timeout = transport.requests[0]
+        self.assertEqual(method, "GET")
+        self.assertEqual(url, "https://example.test/api/v1/posts?limit=5&tag=machine-learning")
+        self.assertEqual(headers["User-Agent"], "sudhanva-python/0.1.0")
+        self.assertIsNone(body)
+        self.assertEqual(timeout, 10.0)
+
+    def test_profile_insight_sends_idempotency_key(self):
+        transport = FakeTransport([response(202, {"job_id": "pi_1", "status": "queued"})])
+        client = Client(transport=transport)
+
+        client.create_profile_insight(
+            audience="agent",
+            focus=["production-ml"],
+            idempotency_key="python-test-123",
+        )
+
+        method, _, headers, body, _ = transport.requests[0]
+        self.assertEqual(method, "POST")
+        self.assertEqual(headers["Idempotency-Key"], "python-test-123")
+        self.assertEqual(
+            json.loads(body),
+            {"audience": "agent", "focus": ["production-ml"]},
+        )
+
+    def test_wait_stops_at_terminal_state(self):
+        transport = FakeTransport([
+            response(200, {"status": "running"}),
+            response(200, {"status": "succeeded", "result": {"summary": "done"}}),
+        ])
+        client = Client(transport=transport)
+
+        job = client.wait_for_profile_insight("pi_test", timeout=1, poll_interval=0)
+
+        self.assertEqual(job["status"], "succeeded")
+        self.assertEqual(len(transport.requests), 2)
+
+    def test_ask_uses_site_root_instead_of_api_base(self):
+        transport = FakeTransport([response(200, {"results": []})])
+        client = Client(base_url="https://example.test/api/v1", transport=transport)
+
+        client.ask("Kubernetes", limit=3, mode="summarize")
+
+        _, url, _, body, _ = transport.requests[0]
+        self.assertEqual(url, "https://example.test/ask")
+        self.assertEqual(json.loads(body)["query"]["limit"], 3)
+        self.assertEqual(json.loads(body)["prefer"]["mode"], "summarize")
+
+    def test_structured_errors_are_exposed(self):
+        transport = FakeTransport([
+            response(404, {"error": {"code": "not_found", "message": "Missing"}})
+        ])
+        client = Client(transport=transport)
+
+        with self.assertRaises(APIError) as caught:
+            client.post("missing")
+
+        self.assertEqual(caught.exception.status, 404)
+        self.assertEqual(caught.exception.code, "not_found")
+
+
+if __name__ == "__main__":
+    unittest.main()
+