qforge-sdk 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,24 @@
1
+ name: CI
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ pull_request:
7
+
8
+ jobs:
9
+ test:
10
+ runs-on: ubuntu-latest
11
+ strategy:
12
+ fail-fast: false
13
+ matrix:
14
+ python: ["3.9", "3.10", "3.11", "3.12", "3.13"]
15
+ steps:
16
+ - uses: actions/checkout@v4
17
+ - uses: actions/setup-python@v5
18
+ with:
19
+ python-version: ${{ matrix.python }}
20
+ - run: pip install -e ".[dev]"
21
+ - run: ruff check .
22
+ - run: mypy src
23
+ if: matrix.python != '3.9'
24
+ - run: pytest -q
@@ -0,0 +1,24 @@
1
+ name: Release
2
+
3
+ # Push a tag like v0.1.0 to publish to PyPI. Uses trusted publishing: on
4
+ # pypi.org, add this repository and this workflow as a trusted publisher for
5
+ # the project "qforge-sdk" (no token needed).
6
+ on:
7
+ push:
8
+ tags: ["v*"]
9
+
10
+ jobs:
11
+ publish:
12
+ runs-on: ubuntu-latest
13
+ environment: pypi
14
+ permissions:
15
+ contents: read
16
+ id-token: write
17
+ steps:
18
+ - uses: actions/checkout@v4
19
+ - uses: actions/setup-python@v5
20
+ with:
21
+ python-version: "3.12"
22
+ - run: pip install build
23
+ - run: python -m build
24
+ - uses: pypa/gh-action-pypi-publish@release/v1
@@ -0,0 +1,8 @@
1
+ .venv/
2
+ __pycache__/
3
+ *.egg-info/
4
+ dist/
5
+ build/
6
+ .pytest_cache/
7
+ .mypy_cache/
8
+ .ruff_cache/
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 QForge
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,144 @@
1
+ Metadata-Version: 2.5
2
+ Name: qforge-sdk
3
+ Version: 0.1.0
4
+ Summary: Python client for QForge: generate crystal structures with target properties.
5
+ Project-URL: Documentation, https://github.com/Hilbert-Forge/QForge-python#readme
6
+ Author: QForge
7
+ License-Expression: MIT
8
+ License-File: LICENSE
9
+ Keywords: ase,crystal structures,generative models,materials,pymatgen
10
+ Classifier: Development Status :: 3 - Alpha
11
+ Classifier: Intended Audience :: Science/Research
12
+ Classifier: License :: OSI Approved :: MIT License
13
+ Classifier: Programming Language :: Python :: 3
14
+ Classifier: Topic :: Scientific/Engineering :: Chemistry
15
+ Classifier: Topic :: Scientific/Engineering :: Physics
16
+ Requires-Python: >=3.9
17
+ Requires-Dist: httpx>=0.25
18
+ Provides-Extra: all
19
+ Requires-Dist: ase>=3.22; extra == 'all'
20
+ Requires-Dist: pymatgen>=2023.1; extra == 'all'
21
+ Provides-Extra: ase
22
+ Requires-Dist: ase>=3.22; extra == 'ase'
23
+ Provides-Extra: dev
24
+ Requires-Dist: mypy>=1.8; extra == 'dev'
25
+ Requires-Dist: pytest>=7; extra == 'dev'
26
+ Requires-Dist: ruff>=0.5; extra == 'dev'
27
+ Provides-Extra: pymatgen
28
+ Requires-Dist: pymatgen>=2023.1; extra == 'pymatgen'
29
+ Description-Content-Type: text/markdown
30
+
31
+ # qforge-sdk
32
+
33
+ Python client for QForge: generate crystal structures with the properties you want, then work with them in pymatgen or ASE.
34
+
35
+ ```bash
36
+ pip install qforge-sdk # the client
37
+ pip install "qforge-sdk[pymatgen]" # + Material.to_pymatgen()
38
+ pip install "qforge-sdk[ase]" # + Material.to_ase()
39
+ ```
40
+
41
+ The package installs as `qforge-sdk` and imports as `qforge`.
42
+
43
+ ## Setup
44
+
45
+ 1. In QForge, open **Developers → API keys** and create a key.
46
+ - Give it only the scopes it needs. "Run" spends credits.
47
+ - Set a monthly credit cap.
48
+ 2. Set two environment variables:
49
+
50
+ ```bash
51
+ export QFORGE_API_KEY=qfk_…
52
+ export QFORGE_URL=https://your-qforge # the address you open QForge at
53
+ ```
54
+
55
+ You can also pass them in code: `QForge(api_key=..., base_url=...)`.
56
+
57
+ ## Generate
58
+
59
+ ```python
60
+ from qforge import QForge
61
+
62
+ qf = QForge()
63
+
64
+ job = qf.generate(
65
+ {"band_gap": 3.0}, # property ids: Developers → Properties
66
+ elements=["Fe", "O"],
67
+ n_structures=8,
68
+ model="frost", # "auto", a model id, or pinned: "frost@1"
69
+ check_novelty=True,
70
+ )
71
+ job.wait(on_progress=lambda j: print(j.status, j.progress))
72
+
73
+ for m in job.materials:
74
+ print(m.formula, m.space_group, m.e_above_hull, m.novelty)
75
+ m.save() # FeO.cif
76
+ s = m.to_pymatgen() # pymatgen Structure
77
+ ```
78
+
79
+ The **code builder** in QForge (Developers → Code builder) writes this call for any query you build in the browser.
80
+
81
+ ## Campaigns
82
+
83
+ A campaign keeps generating until it finds enough materials that meet a goal, or it hits a credit or batch limit.
84
+
85
+ ```python
86
+ c = qf.campaign(
87
+ "Wide-gap oxides",
88
+ {"band_gap": 4.0},
89
+ goal={"count": 5, "novel": True, "stable": True},
90
+ max_credits=30,
91
+ max_batches=10,
92
+ )
93
+ c.wait()
94
+ print(c.status, [m.formula for m in c.materials])
95
+ ```
96
+
97
+ ## Library and DFT
98
+
99
+ ```python
100
+ for m in qf.library(search="Fe-O", favourite=True):
101
+ print(m.formula, m.library_id)
102
+
103
+ check = qf.verify_dft(m, max_credits=20) # starts at the quoted price, never above 20
104
+ check.wait() # DFT takes hours; poll every minute
105
+ print(check.verdict, check.e_above_hull)
106
+ ```
107
+
108
+ ## Errors and retries
109
+
110
+ - **Every API error is a `qforge.QForgeError`**, with `.status`, `.code` and `.request_id`. Quote the request id to support.
111
+ - **Specific error classes:**
112
+ - `AuthenticationError` (401)
113
+ - `InsufficientCredits` (402)
114
+ - `PermissionDenied` (403, the key lacks a scope)
115
+ - `NotFound` (404)
116
+ - `Conflict` (409)
117
+ - `RateLimited` (429)
118
+ - `ServerError` (5xx)
119
+ - `JobFailed` (a run, campaign or DFT check failed; failed runs are refunded)
120
+ - `Timeout` (`wait(timeout=…)` ran out)
121
+ - **Automatic retries:** busy (429) and unavailable (502, 503, 504) responses are retried with backoff, honouring `Retry-After`.
122
+ - **No double charges:** calls that spend credits send an `Idempotency-Key`, so a retry is never charged twice.
123
+
124
+ ## Development
125
+
126
+ ```bash
127
+ python -m venv .venv && .venv/bin/pip install -e ".[dev]"
128
+ .venv/bin/pytest
129
+ .venv/bin/ruff check . && .venv/bin/mypy src
130
+ ```
131
+
132
+ The tests use an in-memory fake server and never call a real one.
133
+
134
+ ### Releasing
135
+
136
+ 1. Bump `version` in `pyproject.toml` and `src/qforge/__init__.py`.
137
+ 2. Tag `vX.Y.Z` and push the tag.
138
+ 3. GitHub Actions builds the package and publishes it to PyPI. This uses trusted publishing: add this repo and the `release.yml` workflow as a trusted publisher for `qforge-sdk` on PyPI first.
139
+
140
+ Until it's on PyPI, install from the repo:
141
+
142
+ ```bash
143
+ pip install "git+https://github.com/Hilbert-Forge/QForge-python.git"
144
+ ```
@@ -0,0 +1,114 @@
1
+ # qforge-sdk
2
+
3
+ Python client for QForge: generate crystal structures with the properties you want, then work with them in pymatgen or ASE.
4
+
5
+ ```bash
6
+ pip install qforge-sdk # the client
7
+ pip install "qforge-sdk[pymatgen]" # + Material.to_pymatgen()
8
+ pip install "qforge-sdk[ase]" # + Material.to_ase()
9
+ ```
10
+
11
+ The package installs as `qforge-sdk` and imports as `qforge`.
12
+
13
+ ## Setup
14
+
15
+ 1. In QForge, open **Developers → API keys** and create a key.
16
+ - Give it only the scopes it needs. "Run" spends credits.
17
+ - Set a monthly credit cap.
18
+ 2. Set two environment variables:
19
+
20
+ ```bash
21
+ export QFORGE_API_KEY=qfk_…
22
+ export QFORGE_URL=https://your-qforge # the address you open QForge at
23
+ ```
24
+
25
+ You can also pass them in code: `QForge(api_key=..., base_url=...)`.
26
+
27
+ ## Generate
28
+
29
+ ```python
30
+ from qforge import QForge
31
+
32
+ qf = QForge()
33
+
34
+ job = qf.generate(
35
+ {"band_gap": 3.0}, # property ids: Developers → Properties
36
+ elements=["Fe", "O"],
37
+ n_structures=8,
38
+ model="frost", # "auto", a model id, or pinned: "frost@1"
39
+ check_novelty=True,
40
+ )
41
+ job.wait(on_progress=lambda j: print(j.status, j.progress))
42
+
43
+ for m in job.materials:
44
+ print(m.formula, m.space_group, m.e_above_hull, m.novelty)
45
+ m.save() # FeO.cif
46
+ s = m.to_pymatgen() # pymatgen Structure
47
+ ```
48
+
49
+ The **code builder** in QForge (Developers → Code builder) writes this call for any query you build in the browser.
50
+
51
+ ## Campaigns
52
+
53
+ A campaign keeps generating until it finds enough materials that meet a goal, or it hits a credit or batch limit.
54
+
55
+ ```python
56
+ c = qf.campaign(
57
+ "Wide-gap oxides",
58
+ {"band_gap": 4.0},
59
+ goal={"count": 5, "novel": True, "stable": True},
60
+ max_credits=30,
61
+ max_batches=10,
62
+ )
63
+ c.wait()
64
+ print(c.status, [m.formula for m in c.materials])
65
+ ```
66
+
67
+ ## Library and DFT
68
+
69
+ ```python
70
+ for m in qf.library(search="Fe-O", favourite=True):
71
+ print(m.formula, m.library_id)
72
+
73
+ check = qf.verify_dft(m, max_credits=20) # starts at the quoted price, never above 20
74
+ check.wait() # DFT takes hours; poll every minute
75
+ print(check.verdict, check.e_above_hull)
76
+ ```
77
+
78
+ ## Errors and retries
79
+
80
+ - **Every API error is a `qforge.QForgeError`**, with `.status`, `.code` and `.request_id`. Quote the request id to support.
81
+ - **Specific error classes:**
82
+ - `AuthenticationError` (401)
83
+ - `InsufficientCredits` (402)
84
+ - `PermissionDenied` (403, the key lacks a scope)
85
+ - `NotFound` (404)
86
+ - `Conflict` (409)
87
+ - `RateLimited` (429)
88
+ - `ServerError` (5xx)
89
+ - `JobFailed` (a run, campaign or DFT check failed; failed runs are refunded)
90
+ - `Timeout` (`wait(timeout=…)` ran out)
91
+ - **Automatic retries:** busy (429) and unavailable (502, 503, 504) responses are retried with backoff, honouring `Retry-After`.
92
+ - **No double charges:** calls that spend credits send an `Idempotency-Key`, so a retry is never charged twice.
93
+
94
+ ## Development
95
+
96
+ ```bash
97
+ python -m venv .venv && .venv/bin/pip install -e ".[dev]"
98
+ .venv/bin/pytest
99
+ .venv/bin/ruff check . && .venv/bin/mypy src
100
+ ```
101
+
102
+ The tests use an in-memory fake server and never call a real one.
103
+
104
+ ### Releasing
105
+
106
+ 1. Bump `version` in `pyproject.toml` and `src/qforge/__init__.py`.
107
+ 2. Tag `vX.Y.Z` and push the tag.
108
+ 3. GitHub Actions builds the package and publishes it to PyPI. This uses trusted publishing: add this repo and the `release.yml` workflow as a trusted publisher for `qforge-sdk` on PyPI first.
109
+
110
+ Until it's on PyPI, install from the repo:
111
+
112
+ ```bash
113
+ pip install "git+https://github.com/Hilbert-Forge/QForge-python.git"
114
+ ```
@@ -0,0 +1,55 @@
1
+ [build-system]
2
+ requires = ["hatchling>=1.24"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "qforge-sdk"
7
+ version = "0.1.0"
8
+ description = "Python client for QForge: generate crystal structures with target properties."
9
+ readme = "README.md"
10
+ requires-python = ">=3.9"
11
+ license = "MIT"
12
+ authors = [{ name = "QForge" }]
13
+ keywords = ["materials", "crystal structures", "generative models", "pymatgen", "ase"]
14
+ classifiers = [
15
+ "Development Status :: 3 - Alpha",
16
+ "Intended Audience :: Science/Research",
17
+ "License :: OSI Approved :: MIT License",
18
+ "Programming Language :: Python :: 3",
19
+ "Topic :: Scientific/Engineering :: Chemistry",
20
+ "Topic :: Scientific/Engineering :: Physics",
21
+ ]
22
+ dependencies = ["httpx>=0.25"]
23
+
24
+ [project.optional-dependencies]
25
+ pymatgen = ["pymatgen>=2023.1"]
26
+ ase = ["ase>=3.22"]
27
+ all = ["pymatgen>=2023.1", "ase>=3.22"]
28
+ dev = ["pytest>=7", "ruff>=0.5", "mypy>=1.8"]
29
+
30
+ [project.urls]
31
+ Documentation = "https://github.com/Hilbert-Forge/QForge-python#readme"
32
+
33
+ [tool.hatch.build.targets.wheel]
34
+ packages = ["src/qforge"]
35
+
36
+ [tool.pytest.ini_options]
37
+ testpaths = ["tests"]
38
+
39
+ [tool.ruff]
40
+ line-length = 110
41
+ target-version = "py39"
42
+
43
+ [tool.ruff.lint]
44
+ select = ["E", "F", "I", "UP", "B"]
45
+
46
+ [tool.ruff.lint.per-file-ignores]
47
+ "tests/*" = ["E501"]
48
+
49
+ [tool.mypy]
50
+ strict = true
51
+ python_version = "3.10"
52
+
53
+ [[tool.mypy.overrides]]
54
+ module = ["pymatgen.*", "ase.*"]
55
+ ignore_missing_imports = true
@@ -0,0 +1,45 @@
1
+ """QForge: generate crystal structures with target properties, from Python.
2
+
3
+ from qforge import QForge
4
+
5
+ qf = QForge() # QFORGE_API_KEY and QFORGE_URL from the environment
6
+ job = qf.generate({"band_gap": 2.5}, elements=["Fe", "O"], n_structures=4)
7
+ for m in job.wait().materials:
8
+ print(m.formula, m.e_above_hull)
9
+ """
10
+
11
+ __version__ = "0.1.0"
12
+
13
+ from .client import QForge # noqa: E402
14
+ from .errors import ( # noqa: E402
15
+ AuthenticationError,
16
+ Conflict,
17
+ InsufficientCredits,
18
+ JobFailed,
19
+ NotFound,
20
+ PermissionDenied,
21
+ QForgeError,
22
+ RateLimited,
23
+ ServerError,
24
+ Timeout,
25
+ )
26
+ from .models import Campaign, DftCheck, Job, Material # noqa: E402
27
+
28
+ __all__ = [
29
+ "QForge",
30
+ "Job",
31
+ "Material",
32
+ "Campaign",
33
+ "DftCheck",
34
+ "QForgeError",
35
+ "AuthenticationError",
36
+ "PermissionDenied",
37
+ "InsufficientCredits",
38
+ "NotFound",
39
+ "Conflict",
40
+ "RateLimited",
41
+ "ServerError",
42
+ "JobFailed",
43
+ "Timeout",
44
+ "__version__",
45
+ ]
@@ -0,0 +1,123 @@
1
+ """HTTP layer: auth, retries with backoff, idempotency keys, error mapping."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import random
6
+ import time
7
+ import uuid
8
+ from collections.abc import Iterator
9
+ from typing import Any
10
+
11
+ import httpx
12
+
13
+ from . import __version__
14
+ from .errors import QForgeError, error_for
15
+
16
+ RETRY_STATUSES = {429, 502, 503, 504}
17
+
18
+
19
+ class Http:
20
+ def __init__(
21
+ self,
22
+ base_url: str,
23
+ api_key: str,
24
+ *,
25
+ timeout: float = 30.0,
26
+ max_retries: int = 3,
27
+ transport: httpx.BaseTransport | None = None,
28
+ ) -> None:
29
+ self.max_retries = max_retries
30
+ self._client = httpx.Client(
31
+ base_url=base_url.rstrip("/") + "/api",
32
+ timeout=timeout,
33
+ transport=transport,
34
+ headers={
35
+ "Authorization": f"Bearer {api_key}",
36
+ "User-Agent": f"qforge-sdk-python/{__version__}",
37
+ "Accept": "application/json",
38
+ },
39
+ )
40
+
41
+ def close(self) -> None:
42
+ self._client.close()
43
+
44
+ def request(
45
+ self,
46
+ method: str,
47
+ path: str,
48
+ *,
49
+ params: dict[str, Any] | None = None,
50
+ json: Any = None,
51
+ idempotent: bool = False,
52
+ ) -> Any:
53
+ """One API call. POSTs that spend credits send an Idempotency-Key, kept
54
+ across retries, so a retry never charges twice."""
55
+ headers: dict[str, str] = {"X-Request-ID": f"py-{uuid.uuid4().hex[:12]}"}
56
+ if idempotent:
57
+ headers["Idempotency-Key"] = uuid.uuid4().hex
58
+ params = {k: v for k, v in (params or {}).items() if v is not None}
59
+ attempt = 0
60
+ while True:
61
+ try:
62
+ res = self._client.request(method, path, params=params, json=json, headers=headers)
63
+ except httpx.TransportError as exc:
64
+ if attempt >= self.max_retries:
65
+ raise QForgeError(f"Couldn't reach QForge: {exc}") from exc
66
+ attempt += 1
67
+ time.sleep(_backoff(attempt))
68
+ continue
69
+ if res.status_code in RETRY_STATUSES and attempt < self.max_retries:
70
+ attempt += 1
71
+ time.sleep(_retry_after(res) or _backoff(attempt))
72
+ continue
73
+ return _result(res)
74
+
75
+ def get(self, path: str, **params: Any) -> Any:
76
+ return self.request("GET", path, params=params)
77
+
78
+ def pages(
79
+ self, path: str, params: dict[str, Any] | None = None, page_size: int = 50
80
+ ) -> Iterator[dict[str, Any]]:
81
+ """Every item of a paginated list, fetching pages as needed."""
82
+ page = 1
83
+ while True:
84
+ data = self.get(path, **(params or {}), page=page, page_size=page_size)
85
+ items = data.get("results", []) if isinstance(data, dict) else data
86
+ yield from items
87
+ if not isinstance(data, dict) or not data.get("next") or not items:
88
+ return
89
+ page += 1
90
+
91
+
92
+ def _backoff(attempt: int) -> float:
93
+ return min(30.0, 0.5 * 2.0**attempt) * (0.75 + random.random() / 2)
94
+
95
+
96
+ def _retry_after(res: httpx.Response) -> float | None:
97
+ value = res.headers.get("Retry-After")
98
+ try:
99
+ return min(60.0, float(str(value))) if value else None
100
+ except ValueError:
101
+ return None
102
+
103
+
104
+ def _result(res: httpx.Response) -> Any:
105
+ if res.status_code == 204 or not res.content:
106
+ if res.is_success:
107
+ return None
108
+ try:
109
+ body = res.json()
110
+ except ValueError:
111
+ body = res.text
112
+ if res.is_success:
113
+ return body
114
+ detail = body.get("detail") if isinstance(body, dict) else None
115
+ code = body.get("code") if isinstance(body, dict) else None
116
+ message = detail if isinstance(detail, str) else f"HTTP {res.status_code}"
117
+ raise error_for(res.status_code)(
118
+ message,
119
+ status=res.status_code,
120
+ code=code,
121
+ request_id=res.headers.get("X-Request-ID"),
122
+ body=body,
123
+ )