helix-python 0.2.0__py3-none-any.whl

helix/__init__.py

@@ -0,0 +1,3 @@
+from helix.client import HelixClient
+
+__all__ = ["HelixClient"]

helix/client.py

@@ -0,0 +1,122 @@
+"""Official Helix Python SDK — market grounding for AI agents."""
+from __future__ import annotations
+
+import time
+from typing import Any
+
+import requests
+
+
+class HelixError(Exception):
+    pass
+
+
+class HelixClient:
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = "https://helixread.com",
+        timeout: int = 30,
+        max_retries: int = 3,
+    ):
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self._session = requests.Session()
+        self._session.headers["X-API-Key"] = api_key
+
+    def _request(self, method: str, path: str, **kwargs) -> Any:
+        url = f"{self.base_url}{path}"
+        last_err: Exception | None = None
+        for attempt in range(self.max_retries):
+            try:
+                r = self._session.request(method, url, timeout=self.timeout, **kwargs)
+                if r.status_code == 429:
+                    wait = int(r.headers.get("Retry-After", 2 ** attempt))
+                    time.sleep(min(wait, 60))
+                    continue
+                if r.status_code >= 400:
+                    raise HelixError(f"{r.status_code}: {r.text[:500]}")
+                return r.json()
+            except requests.RequestException as e:
+                last_err = e
+                time.sleep(2 ** attempt)
+        raise HelixError(str(last_err))
+
+    def health(self) -> dict:
+        return self._request("GET", "/health")
+
+    def get_context(
+        self,
+        symbols: list[str] | None = None,
+        *,
+        depth: str = "standard",
+        modules: str | None = None,
+        since: str | None = None,
+        citations: bool = False,
+        corpus_q: str | None = None,
+    ) -> dict:
+        params: dict[str, Any] = {"depth": depth}
+        if symbols:
+            params["symbols"] = ",".join(symbols)
+        if modules:
+            params["modules"] = modules
+        if since:
+            params["since"] = since
+        if citations:
+            params["citations"] = "true"
+        if corpus_q:
+            params["corpus_q"] = corpus_q
+        return self._request("GET", "/agent/context", params=params)
+
+    def ticker(self, symbol: str) -> dict:
+        return self._request("GET", f"/ticker/{symbol.upper()}")
+
+    def search(self, query: str) -> dict:
+        return self._request("GET", "/search", params={"q": query})
+
+    def read(self, url: str) -> dict:
+        return self._request("GET", "/read", params={"url": url})
+
+    def create_session(
+        self, symbols: list[str], *, depth: str = "standard", modules: str | None = None,
+    ) -> dict:
+        body = {"symbols": symbols, "depth": depth}
+        if modules:
+            body["modules"] = modules
+        return self._request("POST", "/agent/session", json=body)
+
+    def refresh_session(self, session_id: str) -> dict:
+        return self._request("GET", f"/agent/session/{session_id}/refresh")
+
+    def guard_validate(self, llm_output: str, *, session_id: str | None = None, context: dict | None = None) -> dict:
+        body: dict[str, Any] = {"llm_output": llm_output}
+        if session_id:
+            body["session_id"] = session_id
+        if context:
+            body["context"] = context
+        return self._request("POST", "/guard/validate", json=body)
+
+    def register_webhook(self, url: str, events: list[str]) -> dict:
+        return self._request("POST", "/webhooks", json={"url": url, "events": events})
+
+    def set_watchlist(self, symbols: list[str], *, email: str = "", webhook_url: str = "") -> dict:
+        body: dict = {"symbols": symbols}
+        if email:
+            body["email"] = email
+        if webhook_url:
+            body["webhook_url"] = webhook_url
+        return self._request("POST", "/brief/watchlist", json=body)
+
+    def personal_brief(self, symbols: list[str] | None = None) -> dict:
+        params = {}
+        if symbols:
+            params["symbols"] = ",".join(symbols)
+        return self._request("GET", "/brief/personal", params=params)
+
+    def pricing_plans(self) -> dict:
+        return self._request("GET", "/pricing/plans")
+
+    def regime_history(self, days: int = 365) -> dict:
+        return self._request("GET", "/research/regime-history", params={"days": days})

helix_python-0.2.0.dist-info/METADATA

@@ -0,0 +1,61 @@
+Metadata-Version: 2.4
+Name: helix-python
+Version: 0.2.0
+Summary: Official Helix SDK — market grounding for AI agents
+Project-URL: Homepage, https://helixread.com
+Project-URL: Documentation, https://helixread.com/developers
+Author-email: Helix <hello@helixread.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,finance,grounding,helix,llm,market-data
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business :: Financial
+Requires-Python: >=3.10
+Requires-Dist: requests>=2.28
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# helix-python
+
+Official Python SDK for [Helix](https://helixread.com) — market grounding for AI agents.
+
+## Install
+
+```bash
+pip install helix-python
+```
+
+Grab a free API key (250 requests/day, no card) at [helixread.com](https://helixread.com).
+
+## Quickstart
+
+```python
+from helix import HelixClient
+
+hx = HelixClient(api_key="hx_...", base_url="https://helixread.com")
+ctx = hx.get_context(["NVDA", "AMD"], depth="deep", citations=True)
+print(ctx["regime"], ctx.get("peers"))
+```
+
+## Features (v0.2.0)
+
+- `get_context()` — depth, modules, since-diff, citations
+- `create_session()` / `refresh_session()` — versioned grounding
+- `guard_validate()` — Helix Guard anti-hallucination
+- `register_webhook()`, `set_watchlist()`, `personal_brief()`
+- `regime_history()` — Research API tier
+
+## Starter agents
+
+Download agent zips from [helixread.com/agents](https://helixread.com/agents) (free API key required).
+
+## Docs
+
+- API reference: https://helixread.com/developers
+- OpenAPI: https://helixread.com/docs

helix_python-0.2.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+helix/__init__.py,sha256=awMtFqE7tIXGIvfJi0gZfudhYwclBze3T5imjSPm0Ck,63
+helix/client.py,sha256=Kx3rYv1DumKsqDK1FqQVZJzMN46xFlYoYjcFc6GZxQQ,4297
+helix_python-0.2.0.dist-info/METADATA,sha256=8D9yZw7BrFB_SQNyA_cGas9bTyYa4U40ox9C7O3DJ7g,1850
+helix_python-0.2.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+helix_python-0.2.0.dist-info/licenses/LICENSE,sha256=Bt4B5UZee5n7bKJmEDlp9SDu21rMW2XboItq2AuP1Ho,1061
+helix_python-0.2.0.dist-info/RECORD,,

helix_python-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

helix_python-0.2.0.dist-info/licenses/LICENSE

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