prefect-fxmacrodata 0.1.0__tar.gz

prefect_fxmacrodata-0.1.0/CAPABILITIES.md

@@ -0,0 +1,95 @@
+# Operation coverage
+
+This release exposes all 79 operations in the public-client 0.1.1 inventory:
+29 REST operations (28 GET, 1 POST) and 50 hosted MCP tools. Each is a named Prefect task
+imported from `prefect_fxmacrodata.tasks`; exact input schemas are available through
+`operation_schemas()`. This inventory is the service snapshot verified on 2026-09-11.
+
+| Task | Transport and path | Complete history |
+| --- | --- | --- |
+| `health` | `GET /v1/health` | Not offset-paginated |
+| `ping` | `GET /v1/ping` | Not offset-paginated |
+| `forex` | `GET /v1/forex/{base}/{quote}` | `complete_history` |
+| `intraday_reference_rates` | `GET /v1/fx/intraday-reference-rates/{base}/{quote}` | Not offset-paginated |
+| `fx_sources` | `GET /v1/fx/sources` | Not offset-paginated |
+| `fx_source_universe` | `GET /v1/fx/source-universe` | Not offset-paginated |
+| `data_catalogue` | `GET /v1/data_catalogue/{currency}` | Not offset-paginated |
+| `release_calendar` | `GET /v1/calendar/{currency}` | Not offset-paginated |
+| `market_sessions` | `GET /v1/market_sessions` | Not offset-paginated |
+| `rate_differentials` | `GET /v1/rate_differentials/{base}/{quote}` | `complete_history` |
+| `curves` | `GET /v1/curves/{currency}` | Not offset-paginated |
+| `financial_prices` | `GET /v1/financial_prices/{currency}` | `complete_history` |
+| `press_releases` | `GET /v1/press-releases/{currency}` | `complete_history` |
+| `risk_sentiment` | `GET /v1/risk_sentiment` | `complete_history` |
+| `factors` | `GET /v1/factors/{currency}/{factor}` | `complete_history` |
+| `event_predictions` | `GET /v1/predictions/{currency}/{indicator}` | `complete_history` |
+| `latest_announcements` | `GET /v1/announcements/{currency}/latest` | Not offset-paginated |
+| `indicator_history` | `GET /v1/announcements/{currency}/{indicator}` | `complete_history` |
+| `cot` | `GET /v1/cot/{currency}` | `complete_history` |
+| `latest_commodities` | `GET /v1/commodities/latest` | Not offset-paginated |
+| `commodities` | `GET /v1/commodities/{indicator}` | `complete_history` |
+| `announcement_changes` | `GET /v1/announcements/changes` | Not offset-paginated |
+| `stream_events` | `GET /v1/stream/events` | Not offset-paginated |
+| `reference_rates` | `GET /v1/fx/reference-rates/{base}/{quote}` | `complete_history` |
+| `session_rates` | `GET /v1/fx/session-rates/{base}/{quote}` | `complete_history` |
+| `prediction_coverage` | `GET /v1/predictions/coverage` | Not offset-paginated |
+| `currency_prediction_coverage` | `GET /v1/predictions/coverage/{currency}` | Not offset-paginated |
+| `currency_predictions` | `GET /v1/predictions/{currency}` | Not offset-paginated |
+| `research_panel` | `POST /v1/research/panel` | Not offset-paginated |
+| `mcp_ping` | `MCP /mcp` | Not offset-paginated |
+| `mcp_mcp_capabilities` | `MCP /mcp` | Not offset-paginated |
+| `mcp_mcp_auth_guide` | `MCP /mcp` | Not offset-paginated |
+| `mcp_subscribe_for_mcp_access` | `MCP /mcp` | Not offset-paginated |
+| `mcp_data_catalogue` | `MCP /mcp` | Not offset-paginated |
+| `mcp_risk_sentiment` | `MCP /mcp` | Not offset-paginated |
+| `mcp_macro_news` | `MCP /mcp` | Not offset-paginated |
+| `mcp_release_calendar` | `MCP /mcp` | Not offset-paginated |
+| `mcp_release_calendar_visual_artifact` | `MCP /mcp` | Not offset-paginated |
+| `mcp_event_predictions` | `MCP /mcp` | Not offset-paginated |
+| `mcp_latest_announcements` | `MCP /mcp` | Not offset-paginated |
+| `mcp_announcement_changes` | `MCP /mcp` | Not offset-paginated |
+| `mcp_press_releases` | `MCP /mcp` | Not offset-paginated |
+| `mcp_macro_factor` | `MCP /mcp` | Not offset-paginated |
+| `mcp_fx_reference_sources` | `MCP /mcp` | Not offset-paginated |
+| `mcp_fx_reference_universe` | `MCP /mcp` | Not offset-paginated |
+| `mcp_fx_intraday_reference_rates` | `MCP /mcp` | Not offset-paginated |
+| `mcp_rate_curve` | `MCP /mcp` | Not offset-paginated |
+| `mcp_rate_differentials` | `MCP /mcp` | Not offset-paginated |
+| `mcp_latest_commodities` | `MCP /mcp` | Not offset-paginated |
+| `mcp_forex` | `MCP /mcp` | Not offset-paginated |
+| `mcp_seasonality` | `MCP /mcp` | Not offset-paginated |
+| `mcp_indicator_query` | `MCP /mcp` | Not offset-paginated |
+| `mcp_plot_visual_artifact` | `MCP /mcp` | Not offset-paginated |
+| `mcp_indicator_visual_artifact` | `MCP /mcp` | Not offset-paginated |
+| `mcp_forex_visual_artifact` | `MCP /mcp` | Not offset-paginated |
+| `mcp_commodities_visual_artifact` | `MCP /mcp` | Not offset-paginated |
+| `mcp_cot_visual_artifact` | `MCP /mcp` | Not offset-paginated |
+| `mcp_policy_rate_differential_visual_artifact` | `MCP /mcp` | Not offset-paginated |
+| `mcp_macro_briefing_task` | `MCP /mcp` | Not offset-paginated |
+| `mcp_indicator_intel_task` | `MCP /mcp` | Not offset-paginated |
+| `mcp_pair_intel_task` | `MCP /mcp` | Not offset-paginated |
+| `mcp_macro_heatmap_task` | `MCP /mcp` | Not offset-paginated |
+| `mcp_policy_scenario_modeler_task` | `MCP /mcp` | Not offset-paginated |
+| `mcp_macro_war_room_task` | `MCP /mcp` | Not offset-paginated |
+| `mcp_event_impact_replay_task` | `MCP /mcp` | Not offset-paginated |
+| `mcp_quant_scenario_lab_task` | `MCP /mcp` | Not offset-paginated |
+| `mcp_known_at_time_task` | `MCP /mcp` | Not offset-paginated |
+| `mcp_macro_regime_classifier_task` | `MCP /mcp` | Not offset-paginated |
+| `mcp_release_risk_score_task` | `MCP /mcp` | Not offset-paginated |
+| `mcp_portfolio_risk_engine_task` | `MCP /mcp` | Not offset-paginated |
+| `mcp_fx_trade_setup_task` | `MCP /mcp` | Not offset-paginated |
+| `mcp_fx_backtest_task` | `MCP /mcp` | Not offset-paginated |
+| `mcp_macro_research_pack_task` | `MCP /mcp` | Not offset-paginated |
+| `mcp_prediction_coverage` | `MCP /mcp` | Not offset-paginated |
+| `mcp_market_sessions` | `MCP /mcp` | Not offset-paginated |
+| `mcp_cot_data` | `MCP /mcp` | Not offset-paginated |
+| `mcp_commodities` | `MCP /mcp` | Not offset-paginated |
+| `mcp_financial_prices` | `MCP /mcp` | Not offset-paginated |
+| `mcp_official_dataset_family` | `MCP /mcp` | Not offset-paginated |
+
+All tasks return `FXMacroDataResult` with the original payload, provenance and an additive
+record view. No endpoint payload is replaced with a target-specific schema. MCP artefact
+content is retained in the result for downstream tasks; this collection does not execute
+embedded HTML or scripts. Streaming remains a finite capture with completion metadata.
+
+[FXMacroData reference](https://fxmacrodata.com/documentation/reference?utm_source=github&utm_medium=referral&utm_campaign=prefect&utm_content=docs)

prefect_fxmacrodata-0.1.0/LICENSE

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

prefect_fxmacrodata-0.1.0/MANIFEST.in

@@ -0,0 +1,16 @@
+include CAPABILITIES.md
+include LICENSE
+include MANIFEST.in
+include PUBLIC_FILES.json
+include README.md
+include pyproject.toml
+include prefect_fxmacrodata/__init__.py
+include prefect_fxmacrodata/credentials.py
+include prefect_fxmacrodata/flows.py
+include prefect_fxmacrodata/models.py
+include prefect_fxmacrodata/tasks.py
+include prefect_fxmacrodata/tasks.pyi
+include prefect_fxmacrodata/py.typed
+include tests/conftest.py
+include tests/test_tasks.py
+include tests/test_runtime.py

prefect_fxmacrodata-0.1.0/PKG-INFO

@@ -0,0 +1,169 @@
+Metadata-Version: 2.4
+Name: prefect-fxmacrodata
+Version: 0.1.0
+Summary: FXMacroData subscription data in Prefect tasks and research flows
+License-Expression: MIT
+Project-URL: Homepage, https://fxmacrodata.com/?utm_source=github&utm_medium=referral&utm_campaign=prefect&utm_content=readme
+Project-URL: Subscribe, https://fxmacrodata.com/subscribe?utm_source=github&utm_medium=referral&utm_campaign=prefect&utm_content=subscribe
+Project-URL: Documentation, https://fxmacrodata.com/documentation/reference?utm_source=github&utm_medium=referral&utm_campaign=prefect&utm_content=docs
+Requires-Python: <3.15,>=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: prefect<4,>=3.9.1
+Requires-Dist: fxmacrodata-public-client==0.1.1
+Dynamic: license-file
+
+# FXMacroData for Prefect
+
+Bring your FXMacroData subscription into scheduled Prefect research workflows:
+cross-currency indicators, complete available histories, FX reference rates,
+commodities, positioning and release analysis. Store your API key in a Prefect
+Credentials Block and pass its name to native tasks.
+
+**[Subscribe to FXMacroData](https://fxmacrodata.com/subscribe?utm_source=github&utm_medium=referral&utm_campaign=prefect&utm_content=subscribe)**
+for subscriber coverage and deeper available history. Public USD catalogue,
+recent indicator history and calendar access let you evaluate the workflow
+before subscribing without an API key. Availability varies by dataset.
+
+## Install and connect
+
+Use Python 3.10–3.14 and Prefect 3.9.1 or later within version 3. From the release artifacts directory,
+install the adapter wheel into the environment that runs your flows. Its pinned
+FXMacroData public client is available on PyPI and resolves automatically:
+
+```bash
+python -m pip install ./prefect_fxmacrodata-0.1.0-py3-none-any.whl
+prefect block register -m prefect_fxmacrodata
+```
+
+The adapter uses the supplied release artifact; its public-client dependency
+comes from PyPI. Configure your Prefect server or Cloud workspace through Prefect's
+normal setup. In **Blocks**, create an **FXMacroData Credentials** block, enter
+your subscription API key and save it as `fxmacrodata-research`. The key uses
+Prefect's secret-field storage. The timeout controls each HTTP request, in seconds.
+
+To create the same block interactively without putting a key in source code:
+
+```python
+from getpass import getpass
+from pydantic import SecretStr
+from prefect_fxmacrodata import FXMacroDataCredentials
+
+FXMacroDataCredentials(
+    api_key=SecretStr(getpass("FXMacroData API key: ")),
+).save("fxmacrodata-research")
+```
+
+Create the block during setup, outside a flow. Flows and tasks take only its name;
+do not put keys in flow parameters, operation arguments or logs. Omitting
+`credentials_block` explicitly uses public evaluation access, even if an API-key
+environment variable is set.
+
+## Build a research flow
+
+`macro_snapshot` is a Prefect subflow that collects every available history page
+for the selected series and retrieves its release calendar. Pass the typed
+snapshot to your own downstream task:
+
+```python
+import asyncio
+from prefect import flow, task
+from prefect_fxmacrodata import MacroSnapshot, macro_snapshot
+
+
+@task(persist_result=False)
+def count_observations(snapshot: MacroSnapshot) -> int:
+    return len(snapshot.history.records())
+
+
+@flow(persist_result=False)
+async def research_run():
+    snapshot = await macro_snapshot(
+        "EUR",
+        "policy_rate",
+        credentials_block="fxmacrodata-research",
+        start_date="2020-01-01",
+        end_date="2026-01-01",
+    )
+    return count_observations(snapshot)
+
+
+if __name__ == "__main__":
+    asyncio.run(research_run())
+```
+
+To evaluate with USD, omit the credentials and historical date range:
+
+```python
+snapshot = await macro_snapshot("USD", "policy_rate")
+```
+
+Subscriber history can extend beyond the public evaluation window where the
+series supports it.
+Deploy or schedule this flow with your normal Prefect work pool and deployment process.
+The date filters select indicator history. The calendar uses the API's current
+release-calendar window for the currency; it is not filtered to the historical
+range or one indicator. Use the `release_calendar` task directly for different
+calendar filters.
+
+## Use individual operations
+
+Every packaged operation is a named Prefect task, with normal task states,
+dependencies, `with_options`, retries and scheduling through its enclosing flow.
+Both REST and hosted MCP operations are available:
+
+```python
+from prefect_fxmacrodata import operation_schemas
+from prefect_fxmacrodata.tasks import indicator_history, mcp_macro_briefing_task
+
+
+async def inspect_series():
+    page = await indicator_history(
+        {"currency": "GBP", "indicator": "inflation", "limit": 100},
+        credentials_block="fxmacrodata-research",
+    )
+    briefing = await mcp_macro_briefing_task(
+        {"currency": "GBP"},
+        credentials_block="fxmacrodata-research",
+    )
+    return page, briefing
+
+
+schemas = {operation.name: operation.input_schema for operation in operation_schemas()}
+```
+
+See [CAPABILITIES.md](CAPABILITIES.md) for the exact operation inventory. The
+original input schemas are available through `operation_schemas()` or the native
+`discover_operations` task. `OPERATION_TASKS[name]` supports configuration-driven
+flows without losing operation-specific task names.
+
+Results are `FXMacroDataResult` models. `payload` retains the entire service
+response, including original units, provenance, unavailable values and MCP
+content; `source_url` records the source endpoint. `records()` adds a convenient
+row view without replacing the payload. No publication timestamps or missing
+observations are inferred.
+
+## History and failure behavior
+
+Individual operation tasks return a single response using the API's pagination
+rules. Use `complete_history("indicator_history", arguments, credentials_block)`
+for a complete available dataset within the requested filters. It starts at
+offset zero, verifies contiguous pages and dataset versions when supplied, and
+fails if completion cannot be established. Its payload retains every page's
+metadata and returns rows in chronological order. `max_pages` is an explicit
+safety budget; an error never passes an incomplete history off as complete.
+Applications that need resumable storage can persist individual page responses
+and control `offset` and `dataset_version` through the named operation tasks.
+
+Event streaming is a bounded capture using `max_events` and `max_seconds`.
+The response retains the original completion flag and reason. Cancellation
+finishes the current bounded HTTP request, closes the client, and stops before
+the next history page. MCP sessions are closed after each task.
+
+Tasks disable result persistence and caching by default. Opt in only when the
+destination and access controls suit your data licence. Task errors omit raw
+responses, authenticated URLs and credentials. Transient retries are opt-in with
+Prefect's `with_options(retries=..., retry_delay_seconds=...)`.
+
+[FXMacroData API reference](https://fxmacrodata.com/documentation/reference?utm_source=github&utm_medium=referral&utm_campaign=prefect&utm_content=docs)
+describes access requirements and supported arguments for each dataset.

prefect_fxmacrodata-0.1.0/PUBLIC_FILES.json

@@ -0,0 +1,20 @@
+{
+  "files": [
+    "CAPABILITIES.md",
+    "LICENSE",
+    "MANIFEST.in",
+    "PUBLIC_FILES.json",
+    "README.md",
+    "pyproject.toml",
+    "prefect_fxmacrodata/__init__.py",
+    "prefect_fxmacrodata/credentials.py",
+    "prefect_fxmacrodata/flows.py",
+    "prefect_fxmacrodata/models.py",
+    "prefect_fxmacrodata/tasks.py",
+    "prefect_fxmacrodata/tasks.pyi",
+    "prefect_fxmacrodata/py.typed",
+    "tests/conftest.py",
+    "tests/test_tasks.py",
+    "tests/test_runtime.py"
+  ]
+}

prefect_fxmacrodata-0.1.0/README.md

@@ -0,0 +1,154 @@
+# FXMacroData for Prefect
+
+Bring your FXMacroData subscription into scheduled Prefect research workflows:
+cross-currency indicators, complete available histories, FX reference rates,
+commodities, positioning and release analysis. Store your API key in a Prefect
+Credentials Block and pass its name to native tasks.
+
+**[Subscribe to FXMacroData](https://fxmacrodata.com/subscribe?utm_source=github&utm_medium=referral&utm_campaign=prefect&utm_content=subscribe)**
+for subscriber coverage and deeper available history. Public USD catalogue,
+recent indicator history and calendar access let you evaluate the workflow
+before subscribing without an API key. Availability varies by dataset.
+
+## Install and connect
+
+Use Python 3.10–3.14 and Prefect 3.9.1 or later within version 3. From the release artifacts directory,
+install the adapter wheel into the environment that runs your flows. Its pinned
+FXMacroData public client is available on PyPI and resolves automatically:
+
+```bash
+python -m pip install ./prefect_fxmacrodata-0.1.0-py3-none-any.whl
+prefect block register -m prefect_fxmacrodata
+```
+
+The adapter uses the supplied release artifact; its public-client dependency
+comes from PyPI. Configure your Prefect server or Cloud workspace through Prefect's
+normal setup. In **Blocks**, create an **FXMacroData Credentials** block, enter
+your subscription API key and save it as `fxmacrodata-research`. The key uses
+Prefect's secret-field storage. The timeout controls each HTTP request, in seconds.
+
+To create the same block interactively without putting a key in source code:
+
+```python
+from getpass import getpass
+from pydantic import SecretStr
+from prefect_fxmacrodata import FXMacroDataCredentials
+
+FXMacroDataCredentials(
+    api_key=SecretStr(getpass("FXMacroData API key: ")),
+).save("fxmacrodata-research")
+```
+
+Create the block during setup, outside a flow. Flows and tasks take only its name;
+do not put keys in flow parameters, operation arguments or logs. Omitting
+`credentials_block` explicitly uses public evaluation access, even if an API-key
+environment variable is set.
+
+## Build a research flow
+
+`macro_snapshot` is a Prefect subflow that collects every available history page
+for the selected series and retrieves its release calendar. Pass the typed
+snapshot to your own downstream task:
+
+```python
+import asyncio
+from prefect import flow, task
+from prefect_fxmacrodata import MacroSnapshot, macro_snapshot
+
+
+@task(persist_result=False)
+def count_observations(snapshot: MacroSnapshot) -> int:
+    return len(snapshot.history.records())
+
+
+@flow(persist_result=False)
+async def research_run():
+    snapshot = await macro_snapshot(
+        "EUR",
+        "policy_rate",
+        credentials_block="fxmacrodata-research",
+        start_date="2020-01-01",
+        end_date="2026-01-01",
+    )
+    return count_observations(snapshot)
+
+
+if __name__ == "__main__":
+    asyncio.run(research_run())
+```
+
+To evaluate with USD, omit the credentials and historical date range:
+
+```python
+snapshot = await macro_snapshot("USD", "policy_rate")
+```
+
+Subscriber history can extend beyond the public evaluation window where the
+series supports it.
+Deploy or schedule this flow with your normal Prefect work pool and deployment process.
+The date filters select indicator history. The calendar uses the API's current
+release-calendar window for the currency; it is not filtered to the historical
+range or one indicator. Use the `release_calendar` task directly for different
+calendar filters.
+
+## Use individual operations
+
+Every packaged operation is a named Prefect task, with normal task states,
+dependencies, `with_options`, retries and scheduling through its enclosing flow.
+Both REST and hosted MCP operations are available:
+
+```python
+from prefect_fxmacrodata import operation_schemas
+from prefect_fxmacrodata.tasks import indicator_history, mcp_macro_briefing_task
+
+
+async def inspect_series():
+    page = await indicator_history(
+        {"currency": "GBP", "indicator": "inflation", "limit": 100},
+        credentials_block="fxmacrodata-research",
+    )
+    briefing = await mcp_macro_briefing_task(
+        {"currency": "GBP"},
+        credentials_block="fxmacrodata-research",
+    )
+    return page, briefing
+
+
+schemas = {operation.name: operation.input_schema for operation in operation_schemas()}
+```
+
+See [CAPABILITIES.md](CAPABILITIES.md) for the exact operation inventory. The
+original input schemas are available through `operation_schemas()` or the native
+`discover_operations` task. `OPERATION_TASKS[name]` supports configuration-driven
+flows without losing operation-specific task names.
+
+Results are `FXMacroDataResult` models. `payload` retains the entire service
+response, including original units, provenance, unavailable values and MCP
+content; `source_url` records the source endpoint. `records()` adds a convenient
+row view without replacing the payload. No publication timestamps or missing
+observations are inferred.
+
+## History and failure behavior
+
+Individual operation tasks return a single response using the API's pagination
+rules. Use `complete_history("indicator_history", arguments, credentials_block)`
+for a complete available dataset within the requested filters. It starts at
+offset zero, verifies contiguous pages and dataset versions when supplied, and
+fails if completion cannot be established. Its payload retains every page's
+metadata and returns rows in chronological order. `max_pages` is an explicit
+safety budget; an error never passes an incomplete history off as complete.
+Applications that need resumable storage can persist individual page responses
+and control `offset` and `dataset_version` through the named operation tasks.
+
+Event streaming is a bounded capture using `max_events` and `max_seconds`.
+The response retains the original completion flag and reason. Cancellation
+finishes the current bounded HTTP request, closes the client, and stops before
+the next history page. MCP sessions are closed after each task.
+
+Tasks disable result persistence and caching by default. Opt in only when the
+destination and access controls suit your data licence. Task errors omit raw
+responses, authenticated URLs and credentials. Transient retries are opt-in with
+Prefect's `with_options(retries=..., retry_delay_seconds=...)`.
+
+[FXMacroData API reference](https://fxmacrodata.com/documentation/reference?utm_source=github&utm_medium=referral&utm_campaign=prefect&utm_content=docs)
+describes access requirements and supported arguments for each dataset.

prefect_fxmacrodata-0.1.0/prefect_fxmacrodata/__init__.py

@@ -0,0 +1,19 @@
+"""FXMacroData credentials, tasks and research flows for Prefect."""
+
+from .credentials import FXMacroDataCredentials
+from .flows import macro_snapshot
+from .models import FXMacroDataResult, MacroSnapshot, OperationSchema
+from .tasks import OPERATION_TASKS, complete_history, discover_operations, operation_schemas
+
+__version__ = "0.1.0"
+__all__ = [
+    "FXMacroDataCredentials",
+    "FXMacroDataResult",
+    "MacroSnapshot",
+    "OperationSchema",
+    "OPERATION_TASKS",
+    "complete_history",
+    "discover_operations",
+    "macro_snapshot",
+    "operation_schemas",
+]

prefect_fxmacrodata-0.1.0/prefect_fxmacrodata/credentials.py

@@ -0,0 +1,30 @@
+"""Reusable FXMacroData connection configuration for Prefect."""
+
+from fxmacrodata_public import FXMacroDataClient
+from prefect.blocks.core import Block
+from pydantic import Field, SecretStr
+
+
+class FXMacroDataCredentials(Block):
+    """Store a subscriber's API key using Prefect's encrypted secret field.
+
+    Tasks take the saved Block name and load this configuration inside the run.
+    An empty key explicitly selects public evaluation access.
+    """
+
+    _block_type_name = "FXMacroData Credentials"
+    _documentation_url = (
+        "https://fxmacrodata.com/documentation/reference?utm_source=github"
+        "&utm_medium=referral&utm_campaign=prefect&utm_content=docs"
+    )
+
+    api_key: SecretStr = Field(
+        default_factory=lambda: SecretStr(""),
+        description="Your FXMacroData subscription API key; leave empty for USD evaluation.",
+        repr=False,
+    )
+    timeout: float = Field(default=30, ge=1, le=120, allow_inf_nan=False)
+
+    def get_client(self) -> FXMacroDataClient:
+        """Create a bounded client; use it as a context manager."""
+        return FXMacroDataClient(api_key=self.api_key.get_secret_value(), timeout=self.timeout)

prefect_fxmacrodata-0.1.0/prefect_fxmacrodata/flows.py

@@ -0,0 +1,42 @@
+"""Research workflows composed from ordinary Prefect tasks."""
+
+import asyncio
+
+from prefect import flow
+
+from .models import MacroSnapshot
+from .tasks import OPERATION_TASKS, complete_history
+
+
+@flow(name="fxmacrodata-macro-snapshot", persist_result=False, log_prints=False)
+async def macro_snapshot(
+    currency: str,
+    indicator: str,
+    credentials_block: str | None = None,
+    start_date: str | None = None,
+    end_date: str | None = None,
+    max_pages: int = 10000,
+) -> MacroSnapshot:
+    """Fetch complete available indicator history and the release calendar.
+
+    The caller chooses the currency and history range; calendar dates use the
+    API's current release-calendar window independently of the history range.
+    Original source fields,
+    values, publication timestamps and unavailable states are retained.
+    """
+    arguments = {"currency": currency, "indicator": indicator}
+    if start_date is not None:
+        arguments["start_date"] = start_date
+    if end_date is not None:
+        arguments["end_date"] = end_date
+    history, calendar = await asyncio.gather(
+        complete_history("indicator_history", arguments, credentials_block, max_pages),
+        OPERATION_TASKS["release_calendar"]({"currency": currency}, credentials_block),
+    )
+    return MacroSnapshot(
+        currency=currency,
+        indicator=indicator,
+        history=history,
+        calendar=calendar,
+        source_urls=list(dict.fromkeys([history.source_url, calendar.source_url])),
+    )

prefect_fxmacrodata-0.1.0/prefect_fxmacrodata/models.py

@@ -0,0 +1,51 @@
+"""Typed envelopes that retain FXMacroData's original responses."""
+
+from copy import deepcopy
+from typing import Any
+
+from fxmacrodata_public import Result
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class FXMacroDataResult(BaseModel):
+    """Original payload and provenance plus an additive row-oriented view."""
+
+    model_config = ConfigDict(frozen=True)
+
+    operation: str
+    payload: Any = Field(repr=False)
+    source_url: str
+
+    @classmethod
+    def from_result(cls, result: Result) -> "FXMacroDataResult":
+        """Copy a client result without changing values or metadata."""
+        return cls(
+            operation=result.operation,
+            payload=deepcopy(result.payload),
+            source_url=result.source_url,
+        )
+
+    def records(self) -> list[dict[str, Any]]:
+        """Return the public client's additive record view."""
+        return Result(self.operation, self.payload, self.source_url).records()
+
+
+class OperationSchema(BaseModel):
+    """Discover a native task and its unchanged API argument schema."""
+
+    name: str
+    description: str
+    method: str
+    path: str
+    input_schema: dict[str, Any]
+    supports_complete_history: bool
+
+
+class MacroSnapshot(BaseModel):
+    """History and scheduled releases for a research flow's next task."""
+
+    currency: str
+    indicator: str
+    history: FXMacroDataResult
+    calendar: FXMacroDataResult
+    source_urls: list[str] = Field(default_factory=list)