generalforecast 0.2.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.
- generalforecast-0.2.0/.gitignore +8 -0
- generalforecast-0.2.0/LICENSE +21 -0
- generalforecast-0.2.0/PKG-INFO +167 -0
- generalforecast-0.2.0/README.md +137 -0
- generalforecast-0.2.0/api/generate.py +1039 -0
- generalforecast-0.2.0/api/openapi.yaml +10928 -0
- generalforecast-0.2.0/pyproject.toml +68 -0
- generalforecast-0.2.0/src/generalforecast/__init__.py +102 -0
- generalforecast-0.2.0/src/generalforecast/__main__.py +8 -0
- generalforecast-0.2.0/src/generalforecast/_api.py +8367 -0
- generalforecast-0.2.0/src/generalforecast/_files.py +196 -0
- generalforecast-0.2.0/src/generalforecast/_operations.py +2095 -0
- generalforecast-0.2.0/src/generalforecast/account.py +302 -0
- generalforecast-0.2.0/src/generalforecast/as_of.py +138 -0
- generalforecast-0.2.0/src/generalforecast/async_client.py +1279 -0
- generalforecast-0.2.0/src/generalforecast/catalog.py +116 -0
- generalforecast-0.2.0/src/generalforecast/cli.py +1257 -0
- generalforecast-0.2.0/src/generalforecast/client.py +1230 -0
- generalforecast-0.2.0/src/generalforecast/command_specs.py +202 -0
- generalforecast-0.2.0/src/generalforecast/commands.py +303 -0
- generalforecast-0.2.0/src/generalforecast/contracts.py +684 -0
- generalforecast-0.2.0/src/generalforecast/credentials.py +308 -0
- generalforecast-0.2.0/src/generalforecast/diagnostics.py +102 -0
- generalforecast-0.2.0/src/generalforecast/errors.py +809 -0
- generalforecast-0.2.0/src/generalforecast/estimators.py +506 -0
- generalforecast-0.2.0/src/generalforecast/frequency.py +519 -0
- generalforecast-0.2.0/src/generalforecast/ipc.py +208 -0
- generalforecast-0.2.0/src/generalforecast/iso.py +76 -0
- generalforecast-0.2.0/src/generalforecast/login.py +174 -0
- generalforecast-0.2.0/src/generalforecast/manifest.py +169 -0
- generalforecast-0.2.0/src/generalforecast/predict_request.py +472 -0
- generalforecast-0.2.0/src/generalforecast/predictor.py +596 -0
- generalforecast-0.2.0/src/generalforecast/predictor_commands.py +1479 -0
- generalforecast-0.2.0/src/generalforecast/py.typed +0 -0
- generalforecast-0.2.0/src/generalforecast/render.py +410 -0
- generalforecast-0.2.0/src/generalforecast/retry.py +422 -0
- generalforecast-0.2.0/src/generalforecast/serialization.py +37 -0
- generalforecast-0.2.0/src/generalforecast/service/__init__.py +4 -0
- generalforecast-0.2.0/src/generalforecast/service/boundary.py +292 -0
- generalforecast-0.2.0/src/generalforecast/service/contracts.py +191 -0
- generalforecast-0.2.0/src/generalforecast/service/interfaces.py +116 -0
- generalforecast-0.2.0/src/generalforecast/service/sdk.py +592 -0
- generalforecast-0.2.0/src/generalforecast/tables.py +539 -0
- generalforecast-0.2.0/src/generalforecast/tabular.py +678 -0
- generalforecast-0.2.0/src/generalforecast/term.py +1383 -0
- generalforecast-0.2.0/src/generalforecast/transport.py +1323 -0
- generalforecast-0.2.0/src/generalforecast/validation.py +157 -0
- generalforecast-0.2.0/tests/__init__.py +0 -0
- generalforecast-0.2.0/tests/conftest.py +191 -0
- generalforecast-0.2.0/tests/fixtures/as_of.json +45 -0
- generalforecast-0.2.0/tests/test_cli_errors.py +652 -0
- generalforecast-0.2.0/tests/test_cli_login.py +221 -0
- generalforecast-0.2.0/tests/test_cli_logs.py +282 -0
- generalforecast-0.2.0/tests/test_cli_output.py +374 -0
- generalforecast-0.2.0/tests/test_cli_term_layout.py +613 -0
- generalforecast-0.2.0/tests/test_hosted.py +777 -0
- generalforecast-0.2.0/tests/test_ipc.py +189 -0
- generalforecast-0.2.0/tests/test_private_files.py +111 -0
- generalforecast-0.2.0/tests/test_sdk_accepted.py +505 -0
- generalforecast-0.2.0/tests/test_sdk_as_of.py +104 -0
- generalforecast-0.2.0/tests/test_sdk_client.py +504 -0
- generalforecast-0.2.0/tests/test_sdk_connection.py +154 -0
- generalforecast-0.2.0/tests/test_sdk_errors.py +238 -0
- generalforecast-0.2.0/tests/test_sdk_login.py +232 -0
- generalforecast-0.2.0/tests/test_sdk_logs.py +96 -0
- generalforecast-0.2.0/tests/test_sdk_retry.py +1110 -0
- generalforecast-0.2.0/tests/test_sdk_runs.py +440 -0
- generalforecast-0.2.0/tests/test_sdk_snapshots.py +312 -0
- generalforecast-0.2.0/tests/test_sdk_transport.py +868 -0
- generalforecast-0.2.0/tests/test_serialization.py +42 -0
- generalforecast-0.2.0/tests/test_tabular.py +399 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 General Forecast, Inc.
|
|
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,167 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: generalforecast
|
|
3
|
+
Version: 0.2.0
|
|
4
|
+
Summary: Python SDK and gf CLI for General Forecast: hosted predictors on structured data foundation models
|
|
5
|
+
Project-URL: Homepage, https://generalforecast.com
|
|
6
|
+
Project-URL: Documentation, https://docs.generalforecast.com
|
|
7
|
+
Project-URL: Repository, https://github.com/generalforecast/generalforecast-sdk-python
|
|
8
|
+
Project-URL: Issues, https://github.com/generalforecast/generalforecast-sdk-python/issues
|
|
9
|
+
Author: General Forecast, Inc.
|
|
10
|
+
License-Expression: MIT
|
|
11
|
+
License-File: LICENSE
|
|
12
|
+
Classifier: Development Status :: 4 - Beta
|
|
13
|
+
Classifier: Intended Audience :: Developers
|
|
14
|
+
Classifier: Intended Audience :: Science/Research
|
|
15
|
+
Classifier: Operating System :: OS Independent
|
|
16
|
+
Classifier: Programming Language :: Python :: 3
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
19
|
+
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
|
|
20
|
+
Classifier: Typing :: Typed
|
|
21
|
+
Requires-Python: >=3.12
|
|
22
|
+
Requires-Dist: httpx==0.28.1
|
|
23
|
+
Requires-Dist: numpy>=2.5.3
|
|
24
|
+
Requires-Dist: pandas>=2.2
|
|
25
|
+
Requires-Dist: pyarrow>=24
|
|
26
|
+
Requires-Dist: pyyaml>=6.0.2
|
|
27
|
+
Provides-Extra: polars
|
|
28
|
+
Requires-Dist: polars<2,>=1.30; extra == 'polars'
|
|
29
|
+
Description-Content-Type: text/markdown
|
|
30
|
+
|
|
31
|
+
# General Forecast
|
|
32
|
+
|
|
33
|
+
The Python SDK and `gf` command line for [General Forecast](https://generalforecast.com):
|
|
34
|
+
predictors on tabular and time series foundation models, run on the hosted service.
|
|
35
|
+
|
|
36
|
+
- Docs: https://docs.generalforecast.com
|
|
37
|
+
- API reference: https://docs.generalforecast.com/api
|
|
38
|
+
|
|
39
|
+
```sh
|
|
40
|
+
uv pip install generalforecast
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
Python 3.12 or later. The package is pure Python; every prediction, check and
|
|
44
|
+
evaluation runs on the service.
|
|
45
|
+
|
|
46
|
+
## Log in
|
|
47
|
+
|
|
48
|
+
```sh
|
|
49
|
+
gf login
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
`gf login` opens your browser and saves a key for this machine. In CI or a
|
|
53
|
+
notebook, set `GF_API_KEY` (and `GF_PROJECT` if the key spans projects) instead.
|
|
54
|
+
|
|
55
|
+
## A predictor from a table
|
|
56
|
+
|
|
57
|
+
A predictor is a directory with a manifest, `gf.yaml`, and the table its context
|
|
58
|
+
comes from.
|
|
59
|
+
|
|
60
|
+
```sh
|
|
61
|
+
mkdir churn && cp customers.csv churn/
|
|
62
|
+
gf init churn # asks for the target and model, writes gf.yaml
|
|
63
|
+
gf check churn # resolves gf.yaml on the service, writes gf.lock
|
|
64
|
+
gf eval churn # scores the held-out rows on the service
|
|
65
|
+
gf push churn # deploys it to production
|
|
66
|
+
gf predict churn --queries new_customers.csv
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
`gf check` uploads the manifest's snapshot and writes the `gf.lock` the service
|
|
70
|
+
answers with (`--upgrade` accepts a newer model digest). `gf eval` needs a
|
|
71
|
+
snapshot context with a `holdout` or `until`, which `gf init` writes. `gf push`
|
|
72
|
+
has the service check the directory again, keep the snapshot's resolved rows
|
|
73
|
+
and register them with the lock as a new revision; a lock that no longer
|
|
74
|
+
matches is refused until `gf check` runs again.
|
|
75
|
+
`gf status`, `gf promote` and `gf rollback` move environments between
|
|
76
|
+
revisions.
|
|
77
|
+
|
|
78
|
+
To score rows with a catalog model without a predictor directory:
|
|
79
|
+
|
|
80
|
+
```sh
|
|
81
|
+
gf predict --model general-forecast/tabicl-v2-classifier \
|
|
82
|
+
--target churned --context customers.csv --queries new_customers.csv
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
`gf model list` shows the catalog with each model's task and per-call limits.
|
|
86
|
+
|
|
87
|
+
## Python
|
|
88
|
+
|
|
89
|
+
```python
|
|
90
|
+
import generalforecast as gf
|
|
91
|
+
|
|
92
|
+
churn = gf.Predictor("churn") # a pushed predictor
|
|
93
|
+
predictions = churn.predict("new_customers.csv")
|
|
94
|
+
|
|
95
|
+
adhoc = gf.Predictor(
|
|
96
|
+
"general-forecast/tabicl-v2-classifier",
|
|
97
|
+
target="churned",
|
|
98
|
+
context="customers.csv",
|
|
99
|
+
)
|
|
100
|
+
predictions = adhoc.predict("new_customers.csv")
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
### Estimators
|
|
104
|
+
|
|
105
|
+
`Classifier`, `Regressor` and `Forecaster` follow scikit-learn's conventions.
|
|
106
|
+
`fit` keeps the labeled rows; `predict` sends them as the context of a hosted
|
|
107
|
+
prediction.
|
|
108
|
+
|
|
109
|
+
```python
|
|
110
|
+
import numpy as np
|
|
111
|
+
import pandas as pd
|
|
112
|
+
import generalforecast as gf
|
|
113
|
+
|
|
114
|
+
clf = gf.Classifier(model="general-forecast/tabicl-v2-classifier")
|
|
115
|
+
clf.fit(X_context, y_context)
|
|
116
|
+
probabilities = clf.predict_proba(X_queries)
|
|
117
|
+
|
|
118
|
+
days = pd.date_range("2025-01-01", periods=60, freq="D")
|
|
119
|
+
history = pd.DataFrame(
|
|
120
|
+
{
|
|
121
|
+
"date": np.tile(days, 2),
|
|
122
|
+
"sku": np.repeat(["a", "b"], 60),
|
|
123
|
+
"units": np.r_[np.arange(60.0) % 7, 10 + np.arange(60.0) % 5],
|
|
124
|
+
}
|
|
125
|
+
)
|
|
126
|
+
fc = gf.Forecaster(target="units", time="date", series="sku", horizon=7)
|
|
127
|
+
fc.fit(history)
|
|
128
|
+
quantiles = fc.forecast() # 0.1, 0.5 and 0.9 for each sku and step
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
A model reads a bounded number of context rows per request. When the training
|
|
132
|
+
rows are more than one request carries, push them as a context with a predictor
|
|
133
|
+
that reads it, or pass `selection=` to draw each query's context from them.
|
|
134
|
+
|
|
135
|
+
## Live contexts
|
|
136
|
+
|
|
137
|
+
A live context is a table on the service that grows as rows arrive; a predictor
|
|
138
|
+
whose manifest names it (`context: {live: events}`) always predicts with the
|
|
139
|
+
latest rows.
|
|
140
|
+
|
|
141
|
+
```sh
|
|
142
|
+
gf context create events --file events.yaml
|
|
143
|
+
gf context append events rows.csv --id event_id
|
|
144
|
+
gf context label events labels.csv --id event_id --target converted
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
```python
|
|
148
|
+
events = gf.Predictor("conversion").context
|
|
149
|
+
events.append(new_rows)
|
|
150
|
+
events.label(ids, outcomes)
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
## The client
|
|
154
|
+
|
|
155
|
+
`gf.Client` and `gf.AsyncClient` cover the whole API: predictors, revisions and
|
|
156
|
+
environments, contexts, snapshots, models, keys and secrets.
|
|
157
|
+
|
|
158
|
+
```python
|
|
159
|
+
with gf.Client() as client:
|
|
160
|
+
checked = client.predictors.check("churn")
|
|
161
|
+
scores = client.predictors.evaluate("churn")
|
|
162
|
+
client.predictors.push("churn", env="staging", wait=True)
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
## License
|
|
166
|
+
|
|
167
|
+
MIT; see [LICENSE](LICENSE).
|
|
@@ -0,0 +1,137 @@
|
|
|
1
|
+
# General Forecast
|
|
2
|
+
|
|
3
|
+
The Python SDK and `gf` command line for [General Forecast](https://generalforecast.com):
|
|
4
|
+
predictors on tabular and time series foundation models, run on the hosted service.
|
|
5
|
+
|
|
6
|
+
- Docs: https://docs.generalforecast.com
|
|
7
|
+
- API reference: https://docs.generalforecast.com/api
|
|
8
|
+
|
|
9
|
+
```sh
|
|
10
|
+
uv pip install generalforecast
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
Python 3.12 or later. The package is pure Python; every prediction, check and
|
|
14
|
+
evaluation runs on the service.
|
|
15
|
+
|
|
16
|
+
## Log in
|
|
17
|
+
|
|
18
|
+
```sh
|
|
19
|
+
gf login
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
`gf login` opens your browser and saves a key for this machine. In CI or a
|
|
23
|
+
notebook, set `GF_API_KEY` (and `GF_PROJECT` if the key spans projects) instead.
|
|
24
|
+
|
|
25
|
+
## A predictor from a table
|
|
26
|
+
|
|
27
|
+
A predictor is a directory with a manifest, `gf.yaml`, and the table its context
|
|
28
|
+
comes from.
|
|
29
|
+
|
|
30
|
+
```sh
|
|
31
|
+
mkdir churn && cp customers.csv churn/
|
|
32
|
+
gf init churn # asks for the target and model, writes gf.yaml
|
|
33
|
+
gf check churn # resolves gf.yaml on the service, writes gf.lock
|
|
34
|
+
gf eval churn # scores the held-out rows on the service
|
|
35
|
+
gf push churn # deploys it to production
|
|
36
|
+
gf predict churn --queries new_customers.csv
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
`gf check` uploads the manifest's snapshot and writes the `gf.lock` the service
|
|
40
|
+
answers with (`--upgrade` accepts a newer model digest). `gf eval` needs a
|
|
41
|
+
snapshot context with a `holdout` or `until`, which `gf init` writes. `gf push`
|
|
42
|
+
has the service check the directory again, keep the snapshot's resolved rows
|
|
43
|
+
and register them with the lock as a new revision; a lock that no longer
|
|
44
|
+
matches is refused until `gf check` runs again.
|
|
45
|
+
`gf status`, `gf promote` and `gf rollback` move environments between
|
|
46
|
+
revisions.
|
|
47
|
+
|
|
48
|
+
To score rows with a catalog model without a predictor directory:
|
|
49
|
+
|
|
50
|
+
```sh
|
|
51
|
+
gf predict --model general-forecast/tabicl-v2-classifier \
|
|
52
|
+
--target churned --context customers.csv --queries new_customers.csv
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
`gf model list` shows the catalog with each model's task and per-call limits.
|
|
56
|
+
|
|
57
|
+
## Python
|
|
58
|
+
|
|
59
|
+
```python
|
|
60
|
+
import generalforecast as gf
|
|
61
|
+
|
|
62
|
+
churn = gf.Predictor("churn") # a pushed predictor
|
|
63
|
+
predictions = churn.predict("new_customers.csv")
|
|
64
|
+
|
|
65
|
+
adhoc = gf.Predictor(
|
|
66
|
+
"general-forecast/tabicl-v2-classifier",
|
|
67
|
+
target="churned",
|
|
68
|
+
context="customers.csv",
|
|
69
|
+
)
|
|
70
|
+
predictions = adhoc.predict("new_customers.csv")
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
### Estimators
|
|
74
|
+
|
|
75
|
+
`Classifier`, `Regressor` and `Forecaster` follow scikit-learn's conventions.
|
|
76
|
+
`fit` keeps the labeled rows; `predict` sends them as the context of a hosted
|
|
77
|
+
prediction.
|
|
78
|
+
|
|
79
|
+
```python
|
|
80
|
+
import numpy as np
|
|
81
|
+
import pandas as pd
|
|
82
|
+
import generalforecast as gf
|
|
83
|
+
|
|
84
|
+
clf = gf.Classifier(model="general-forecast/tabicl-v2-classifier")
|
|
85
|
+
clf.fit(X_context, y_context)
|
|
86
|
+
probabilities = clf.predict_proba(X_queries)
|
|
87
|
+
|
|
88
|
+
days = pd.date_range("2025-01-01", periods=60, freq="D")
|
|
89
|
+
history = pd.DataFrame(
|
|
90
|
+
{
|
|
91
|
+
"date": np.tile(days, 2),
|
|
92
|
+
"sku": np.repeat(["a", "b"], 60),
|
|
93
|
+
"units": np.r_[np.arange(60.0) % 7, 10 + np.arange(60.0) % 5],
|
|
94
|
+
}
|
|
95
|
+
)
|
|
96
|
+
fc = gf.Forecaster(target="units", time="date", series="sku", horizon=7)
|
|
97
|
+
fc.fit(history)
|
|
98
|
+
quantiles = fc.forecast() # 0.1, 0.5 and 0.9 for each sku and step
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
A model reads a bounded number of context rows per request. When the training
|
|
102
|
+
rows are more than one request carries, push them as a context with a predictor
|
|
103
|
+
that reads it, or pass `selection=` to draw each query's context from them.
|
|
104
|
+
|
|
105
|
+
## Live contexts
|
|
106
|
+
|
|
107
|
+
A live context is a table on the service that grows as rows arrive; a predictor
|
|
108
|
+
whose manifest names it (`context: {live: events}`) always predicts with the
|
|
109
|
+
latest rows.
|
|
110
|
+
|
|
111
|
+
```sh
|
|
112
|
+
gf context create events --file events.yaml
|
|
113
|
+
gf context append events rows.csv --id event_id
|
|
114
|
+
gf context label events labels.csv --id event_id --target converted
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
```python
|
|
118
|
+
events = gf.Predictor("conversion").context
|
|
119
|
+
events.append(new_rows)
|
|
120
|
+
events.label(ids, outcomes)
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
## The client
|
|
124
|
+
|
|
125
|
+
`gf.Client` and `gf.AsyncClient` cover the whole API: predictors, revisions and
|
|
126
|
+
environments, contexts, snapshots, models, keys and secrets.
|
|
127
|
+
|
|
128
|
+
```python
|
|
129
|
+
with gf.Client() as client:
|
|
130
|
+
checked = client.predictors.check("churn")
|
|
131
|
+
scores = client.predictors.evaluate("churn")
|
|
132
|
+
client.predictors.push("churn", env="staging", wait=True)
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
## License
|
|
136
|
+
|
|
137
|
+
MIT; see [LICENSE](LICENSE).
|