swarmauri_llm_cloudflare 0.11.0.dev2__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,79 @@
1
+ Metadata-Version: 2.4
2
+ Name: swarmauri_llm_cloudflare
3
+ Version: 0.11.0.dev2
4
+ Summary: Swarmauri chat and tool-calling adapters for Cloudflare Workers AI.
5
+ License-Expression: Apache-2.0
6
+ Keywords: swarmauri,llm,cloudflare,workers ai,tool calling,streaming,openai compatible
7
+ Author: Jacob Stewart
8
+ Author-email: jacob@swarmauri.com
9
+ Requires-Python: >=3.10,<3.13
10
+ Classifier: Development Status :: 1 - Planning
11
+ Classifier: License :: OSI Approved :: Apache Software License
12
+ Classifier: Programming Language :: Python :: 3.10
13
+ Classifier: Programming Language :: Python :: 3.11
14
+ Classifier: Programming Language :: Python :: 3.12
15
+ Requires-Dist: swarmauri_base (>=0.11.0.dev5)
16
+ Requires-Dist: swarmauri_core (>=0.11.0.dev5)
17
+ Requires-Dist: swarmauri_standard (>=0.11.0.dev6)
18
+ Requires-Dist: swarmauri_transport_httpx (>=0.1.0.dev5)
19
+ Requires-Dist: swarmauri_transport_retry (>=0.1.0.dev1)
20
+ Description-Content-Type: text/markdown
21
+
22
+ ![Swarmauri](https://raw.githubusercontent.com/swarmauri/swarmauri-sdk/3d4d1cfa949399d7019ae9d8f296afba773dfb7f/assets/swarmauri.brand.theme.svg)
23
+
24
+ <p align="center">
25
+ <a href="https://pepy.tech/project/swarmauri_llm_cloudflare"><img src="https://static.pepy.tech/badge/swarmauri_llm_cloudflare/month" alt="Downloads"></a>
26
+ <a href="https://hits.sh/github.com/swarmauri/swarmauri-sdk/tree/master/pkgs/community/swarmauri_llm_cloudflare/"><img src="https://hits.sh/github.com/swarmauri/swarmauri-sdk/tree/master/pkgs/community/swarmauri_llm_cloudflare.svg" alt="Hits"></a>
27
+ <a href="https://pypi.org/project/swarmauri_llm_cloudflare/"><img src="https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-blue" alt="Python"></a>
28
+ <a href="https://pypi.org/project/swarmauri_llm_cloudflare/"><img src="https://img.shields.io/pypi/l/swarmauri_llm_cloudflare" alt="License"></a>
29
+ <a href="https://pypi.org/project/swarmauri_llm_cloudflare/"><img src="https://img.shields.io/pypi/v/swarmauri_llm_cloudflare" alt="Release"></a>
30
+ </p>
31
+
32
+ # Swarmauri Cloudflare Workers AI LLM
33
+
34
+ `swarmauri_llm_cloudflare` connects Swarmauri conversations and toolkits to Cloudflare Workers AI's account-scoped REST API.
35
+
36
+ ## Features
37
+
38
+ - OpenAI-compatible chat completions through `CloudflareWorkersAIModel`.
39
+ - Tool calling through `CloudflareWorkersAIToolModel` for models that advertise tool support.
40
+ - Synchronous, asynchronous, incremental streaming, and batch workflows.
41
+ - Optional discovery from Cloudflare's model-search endpoint.
42
+ - Explicit account ID and API-token configuration.
43
+ - Persistent, injectable Swarmauri HTTP clients with conservative rate-limit retries.
44
+
45
+ ## Installation
46
+
47
+ ```bash
48
+ uv add swarmauri_llm_cloudflare
49
+ ```
50
+
51
+ ```bash
52
+ pip install swarmauri_llm_cloudflare
53
+ ```
54
+
55
+ ## Usage
56
+
57
+ ```python
58
+ import os
59
+
60
+ from swarmauri_llm_cloudflare import CloudflareWorkersAIModel
61
+ from swarmauri_standard.conversations.Conversation import Conversation
62
+ from swarmauri_standard.messages.HumanMessage import HumanMessage
63
+
64
+ conversation = Conversation(messages=[HumanMessage(content="Explain edge inference.")])
65
+ model = CloudflareWorkersAIModel(
66
+ account_id=os.environ["CLOUDFLARE_ACCOUNT_ID"],
67
+ api_key=os.environ["CLOUDFLARE_API_TOKEN"],
68
+ name="@cf/meta/llama-3.3-70b-instruct-fp8-fast",
69
+ )
70
+ model.predict(conversation)
71
+ print(conversation.get_last().content)
72
+ ```
73
+
74
+ Set `discover_models=True` to query the current Workers AI model catalog. For tools, instantiate `CloudflareWorkersAIToolModel` with a tool-capable model and pass a Swarmauri `Toolkit`.
75
+
76
+ Pass an `IHttpClient` as `http_client` to integrate a custom transport or to test without network access. Pass an `IHttpRetryPolicy` as `retry_policy` to replace the default policy, which retries safe reads and rate-limited chat submissions without replaying failed POST requests for generic server errors.
77
+
78
+ See the [Cloudflare Workers AI REST guide](https://developers.cloudflare.com/workers-ai/get-started/rest-api/) and [model-search API](https://developers.cloudflare.com/api/resources/ai/subresources/models/methods/list/) for account setup and current model details.
79
+
@@ -0,0 +1,57 @@
1
+ ![Swarmauri](https://raw.githubusercontent.com/swarmauri/swarmauri-sdk/3d4d1cfa949399d7019ae9d8f296afba773dfb7f/assets/swarmauri.brand.theme.svg)
2
+
3
+ <p align="center">
4
+ <a href="https://pepy.tech/project/swarmauri_llm_cloudflare"><img src="https://static.pepy.tech/badge/swarmauri_llm_cloudflare/month" alt="Downloads"></a>
5
+ <a href="https://hits.sh/github.com/swarmauri/swarmauri-sdk/tree/master/pkgs/community/swarmauri_llm_cloudflare/"><img src="https://hits.sh/github.com/swarmauri/swarmauri-sdk/tree/master/pkgs/community/swarmauri_llm_cloudflare.svg" alt="Hits"></a>
6
+ <a href="https://pypi.org/project/swarmauri_llm_cloudflare/"><img src="https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-blue" alt="Python"></a>
7
+ <a href="https://pypi.org/project/swarmauri_llm_cloudflare/"><img src="https://img.shields.io/pypi/l/swarmauri_llm_cloudflare" alt="License"></a>
8
+ <a href="https://pypi.org/project/swarmauri_llm_cloudflare/"><img src="https://img.shields.io/pypi/v/swarmauri_llm_cloudflare" alt="Release"></a>
9
+ </p>
10
+
11
+ # Swarmauri Cloudflare Workers AI LLM
12
+
13
+ `swarmauri_llm_cloudflare` connects Swarmauri conversations and toolkits to Cloudflare Workers AI's account-scoped REST API.
14
+
15
+ ## Features
16
+
17
+ - OpenAI-compatible chat completions through `CloudflareWorkersAIModel`.
18
+ - Tool calling through `CloudflareWorkersAIToolModel` for models that advertise tool support.
19
+ - Synchronous, asynchronous, incremental streaming, and batch workflows.
20
+ - Optional discovery from Cloudflare's model-search endpoint.
21
+ - Explicit account ID and API-token configuration.
22
+ - Persistent, injectable Swarmauri HTTP clients with conservative rate-limit retries.
23
+
24
+ ## Installation
25
+
26
+ ```bash
27
+ uv add swarmauri_llm_cloudflare
28
+ ```
29
+
30
+ ```bash
31
+ pip install swarmauri_llm_cloudflare
32
+ ```
33
+
34
+ ## Usage
35
+
36
+ ```python
37
+ import os
38
+
39
+ from swarmauri_llm_cloudflare import CloudflareWorkersAIModel
40
+ from swarmauri_standard.conversations.Conversation import Conversation
41
+ from swarmauri_standard.messages.HumanMessage import HumanMessage
42
+
43
+ conversation = Conversation(messages=[HumanMessage(content="Explain edge inference.")])
44
+ model = CloudflareWorkersAIModel(
45
+ account_id=os.environ["CLOUDFLARE_ACCOUNT_ID"],
46
+ api_key=os.environ["CLOUDFLARE_API_TOKEN"],
47
+ name="@cf/meta/llama-3.3-70b-instruct-fp8-fast",
48
+ )
49
+ model.predict(conversation)
50
+ print(conversation.get_last().content)
51
+ ```
52
+
53
+ Set `discover_models=True` to query the current Workers AI model catalog. For tools, instantiate `CloudflareWorkersAIToolModel` with a tool-capable model and pass a Swarmauri `Toolkit`.
54
+
55
+ Pass an `IHttpClient` as `http_client` to integrate a custom transport or to test without network access. Pass an `IHttpRetryPolicy` as `retry_policy` to replace the default policy, which retries safe reads and rate-limited chat submissions without replaying failed POST requests for generic server errors.
56
+
57
+ See the [Cloudflare Workers AI REST guide](https://developers.cloudflare.com/workers-ai/get-started/rest-api/) and [model-search API](https://developers.cloudflare.com/api/resources/ai/subresources/models/methods/list/) for account setup and current model details.
@@ -0,0 +1,46 @@
1
+ [project]
2
+ name = "swarmauri_llm_cloudflare"
3
+ version = "0.11.0.dev2"
4
+ description = "Swarmauri chat and tool-calling adapters for Cloudflare Workers AI."
5
+ license = "Apache-2.0"
6
+ readme = "README.md"
7
+ requires-python = ">=3.10,<3.13"
8
+ authors = [{ name = "Jacob Stewart", email = "jacob@swarmauri.com" }]
9
+ keywords = ["swarmauri", "llm", "cloudflare", "workers ai", "tool calling", "streaming", "openai compatible"]
10
+ classifiers = [
11
+ "Development Status :: 1 - Planning",
12
+ "License :: OSI Approved :: Apache Software License",
13
+ "Programming Language :: Python :: 3.10",
14
+ "Programming Language :: Python :: 3.11",
15
+ "Programming Language :: Python :: 3.12",
16
+ ]
17
+ dependencies = [
18
+ "swarmauri_base>=0.11.0.dev5",
19
+ "swarmauri_core>=0.11.0.dev5",
20
+ "swarmauri_standard>=0.11.0.dev6",
21
+ "swarmauri_transport_httpx>=0.1.0.dev5",
22
+ "swarmauri_transport_retry>=0.1.0.dev1",
23
+ ]
24
+
25
+ [tool.uv.sources]
26
+ swarmauri_base = { workspace = true }
27
+ swarmauri_core = { workspace = true }
28
+ swarmauri_standard = { workspace = true }
29
+ swarmauri_transport_httpx = { workspace = true }
30
+ swarmauri_transport_retry = { workspace = true }
31
+
32
+ [project.entry-points."swarmauri.llms"]
33
+ CloudflareWorkersAIModel = "swarmauri_llm_cloudflare:CloudflareWorkersAIModel"
34
+
35
+ [project.entry-points."swarmauri.tool_llms"]
36
+ CloudflareWorkersAIToolModel = "swarmauri_llm_cloudflare:CloudflareWorkersAIToolModel"
37
+
38
+ [build-system]
39
+ requires = ["poetry-core>=1.0.0"]
40
+ build-backend = "poetry.core.masonry.api"
41
+
42
+ [dependency-groups]
43
+ dev = ["pytest>=8.0", "pytest-asyncio>=0.24", "ruff>=0.9.9"]
44
+
45
+ [tool.pytest.ini_options]
46
+ markers = ["unit: Unit tests"]
@@ -0,0 +1,34 @@
1
+ """Retry policy for Cloudflare Workers AI chat operations."""
2
+
3
+ from swarmauri_core.transports.i_http_response import IHttpResponse
4
+ from swarmauri_transport_retry import ExponentialBackoffRetryPolicy
5
+
6
+
7
+ class CloudflareChatRetryPolicy(ExponentialBackoffRetryPolicy):
8
+ """Retry safe reads and rate-limited chat submissions."""
9
+
10
+ def __init__(self, **kwargs) -> None:
11
+ kwargs.setdefault("retryable_methods", {"GET", "POST"})
12
+ super().__init__(**kwargs)
13
+
14
+ def should_retry(
15
+ self,
16
+ *,
17
+ method: str,
18
+ attempt: int,
19
+ response: IHttpResponse | None = None,
20
+ error: Exception | None = None,
21
+ ) -> bool:
22
+ if method.upper() == "POST":
23
+ return (
24
+ attempt < self.max_attempts
25
+ and error is None
26
+ and response is not None
27
+ and response.status_code == 429
28
+ )
29
+ return super().should_retry(
30
+ method=method,
31
+ attempt=attempt,
32
+ response=response,
33
+ error=error,
34
+ )
@@ -0,0 +1,102 @@
1
+ from typing import Any, ClassVar, Literal
2
+
3
+ from pydantic import Field, PrivateAttr
4
+ from swarmauri_base.ComponentBase import ComponentBase
5
+ from swarmauri_base.llms.LLMBase import LLMBase
6
+ from swarmauri_core.transports.i_http_client import IHttpClient
7
+ from swarmauri_core.transports.i_http_retry_policy import IHttpRetryPolicy
8
+ from swarmauri_core.transports.i_managed_http_client import IManagedHttpClient
9
+ from swarmauri_standard.utils.provider_chat_transport import (
10
+ abatch_chat,
11
+ apredict_chat,
12
+ astream_chat,
13
+ batch_chat,
14
+ predict_chat,
15
+ stream_chat,
16
+ )
17
+
18
+ from ._client import build_cloudflare_client
19
+
20
+
21
+ @ComponentBase.register_type()
22
+ class CloudflareWorkersAIModel(LLMBase):
23
+ """Chat adapter for Cloudflare Workers AI."""
24
+
25
+ type: Literal["CloudflareWorkersAIModel"] = "CloudflareWorkersAIModel"
26
+ account_id: str = Field(min_length=1)
27
+ name: str = "@cf/meta/llama-3.3-70b-instruct-fp8-fast"
28
+ base_url: str = "https://api.cloudflare.com/client/v4"
29
+ discover_models: bool = False
30
+ capabilities: ClassVar[frozenset[str]] = frozenset(
31
+ {"chat_completions", "structured_output", "streaming", "tools"}
32
+ )
33
+ _http_client: IHttpClient = PrivateAttr()
34
+ _retry_owned_by_transport: bool = PrivateAttr(default=True)
35
+
36
+ predict = predict_chat
37
+ apredict = apredict_chat
38
+ stream = stream_chat
39
+ astream = astream_chat
40
+ batch = batch_chat
41
+ abatch = abatch_chat
42
+
43
+ def __init__(
44
+ self,
45
+ *,
46
+ http_client: IHttpClient | None = None,
47
+ retry_policy: IHttpRetryPolicy | None = None,
48
+ **data: Any,
49
+ ) -> None:
50
+ selected_name = data.get(
51
+ "name", self.__class__.model_fields["name"].default
52
+ )
53
+ data.setdefault("allowed_models", [selected_name])
54
+ super().__init__(**data)
55
+ self._http_client = build_cloudflare_client(
56
+ base_url=self.base_url,
57
+ timeout=self.timeout,
58
+ max_attempts=self.max_retries,
59
+ http_client=http_client,
60
+ retry_policy=retry_policy,
61
+ )
62
+ if self.discover_models:
63
+ self.allowed_models = self._get_models()
64
+
65
+ def _account_root(self) -> str:
66
+ return f"{self.base_url.rstrip('/')}/accounts/{self.account_id}/ai"
67
+
68
+ def _build_endpoint(self) -> str:
69
+ return f"{self._account_root()}/v1/chat/completions"
70
+
71
+ def _build_headers(self) -> dict[str, str]:
72
+ headers = {"Content-Type": "application/json"}
73
+ if self.api_key is not None:
74
+ headers["Authorization"] = (
75
+ f"Bearer {self.api_key.get_secret_value()}"
76
+ )
77
+ return headers
78
+
79
+ def _get_models(self) -> list[str]:
80
+ if not self.discover_models:
81
+ return [self.name] if self.name else []
82
+ response = self._http_client.request(
83
+ "GET",
84
+ f"{self._account_root()}/models/search",
85
+ headers=self._build_headers(),
86
+ params={"task": "Text Generation", "per_page": 100},
87
+ )
88
+ response.raise_for_status()
89
+ result: list[dict[str, Any]] = response.json().get("result") or []
90
+ return [
91
+ model_name
92
+ for model in result
93
+ if (model_name := model.get("name") or model.get("id"))
94
+ ]
95
+
96
+ def close(self) -> None:
97
+ if isinstance(self._http_client, IManagedHttpClient):
98
+ self._http_client.close()
99
+
100
+ async def aclose(self) -> None:
101
+ if isinstance(self._http_client, IManagedHttpClient):
102
+ await self._http_client.aclose()
@@ -0,0 +1,114 @@
1
+ from typing import Any, ClassVar, Literal
2
+
3
+ from pydantic import Field, PrivateAttr
4
+ from swarmauri_base.ComponentBase import ComponentBase
5
+ from swarmauri_base.tool_llms.ToolLLMBase import ToolLLMBase
6
+ from swarmauri_core.transports.i_http_client import IHttpClient
7
+ from swarmauri_core.transports.i_http_retry_policy import IHttpRetryPolicy
8
+ from swarmauri_core.transports.i_managed_http_client import IManagedHttpClient
9
+ from swarmauri_standard.schema_converters.OpenAISchemaConverter import (
10
+ OpenAISchemaConverter,
11
+ )
12
+ from swarmauri_standard.utils.provider_chat_transport import (
13
+ abatch_tools,
14
+ apredict_tools,
15
+ astream_tools,
16
+ batch_tools,
17
+ format_messages,
18
+ predict_tools,
19
+ stream_tools,
20
+ )
21
+
22
+ from ._client import build_cloudflare_client
23
+
24
+
25
+ @ComponentBase.register_type()
26
+ class CloudflareWorkersAIToolModel(ToolLLMBase):
27
+ """Tool-calling adapter for Cloudflare Workers AI."""
28
+
29
+ type: Literal["CloudflareWorkersAIToolModel"] = (
30
+ "CloudflareWorkersAIToolModel"
31
+ )
32
+ account_id: str = Field(min_length=1)
33
+ name: str = "@cf/openai/gpt-oss-20b"
34
+ base_url: str = "https://api.cloudflare.com/client/v4"
35
+ discover_models: bool = False
36
+ capabilities: ClassVar[frozenset[str]] = frozenset(
37
+ {"chat_completions", "streaming", "tools"}
38
+ )
39
+ _http_client: IHttpClient = PrivateAttr()
40
+ _retry_owned_by_transport: bool = PrivateAttr(default=True)
41
+
42
+ predict = predict_tools
43
+ apredict = apredict_tools
44
+ stream = stream_tools
45
+ astream = astream_tools
46
+ batch = batch_tools
47
+ abatch = abatch_tools
48
+
49
+ def __init__(
50
+ self,
51
+ *,
52
+ http_client: IHttpClient | None = None,
53
+ retry_policy: IHttpRetryPolicy | None = None,
54
+ **data: Any,
55
+ ) -> None:
56
+ selected_name = data.get(
57
+ "name", self.__class__.model_fields["name"].default
58
+ )
59
+ data.setdefault("allowed_models", [selected_name])
60
+ super().__init__(**data)
61
+ self._http_client = build_cloudflare_client(
62
+ base_url=self.base_url,
63
+ timeout=self.timeout,
64
+ max_attempts=self.max_retries,
65
+ http_client=http_client,
66
+ retry_policy=retry_policy,
67
+ )
68
+ if self.discover_models:
69
+ self.allowed_models = self._get_models()
70
+
71
+ def get_schema_converter(self):
72
+ return OpenAISchemaConverter()
73
+
74
+ def _format_messages(self, messages):
75
+ return format_messages(messages)
76
+
77
+ def _account_root(self) -> str:
78
+ return f"{self.base_url.rstrip('/')}/accounts/{self.account_id}/ai"
79
+
80
+ def _build_endpoint(self) -> str:
81
+ return f"{self._account_root()}/v1/chat/completions"
82
+
83
+ def _build_headers(self) -> dict[str, str]:
84
+ headers = {"Content-Type": "application/json"}
85
+ if self.api_key is not None:
86
+ headers["Authorization"] = (
87
+ f"Bearer {self.api_key.get_secret_value()}"
88
+ )
89
+ return headers
90
+
91
+ def _get_models(self) -> list[str]:
92
+ if not self.discover_models:
93
+ return [self.name] if self.name else []
94
+ response = self._http_client.request(
95
+ "GET",
96
+ f"{self._account_root()}/models/search",
97
+ headers=self._build_headers(),
98
+ params={"task": "Text Generation", "per_page": 100},
99
+ )
100
+ response.raise_for_status()
101
+ result: list[dict[str, Any]] = response.json().get("result") or []
102
+ return [
103
+ model_name
104
+ for model in result
105
+ if (model_name := model.get("name") or model.get("id"))
106
+ ]
107
+
108
+ def close(self) -> None:
109
+ if isinstance(self._http_client, IManagedHttpClient):
110
+ self._http_client.close()
111
+
112
+ async def aclose(self) -> None:
113
+ if isinstance(self._http_client, IManagedHttpClient):
114
+ await self._http_client.aclose()
@@ -0,0 +1,16 @@
1
+ from importlib.metadata import PackageNotFoundError, version
2
+
3
+ from .CloudflareChatRetryPolicy import CloudflareChatRetryPolicy
4
+ from .CloudflareWorkersAIModel import CloudflareWorkersAIModel
5
+ from .CloudflareWorkersAIToolModel import CloudflareWorkersAIToolModel
6
+
7
+ try:
8
+ __version__ = version("swarmauri_llm_cloudflare")
9
+ except PackageNotFoundError:
10
+ __version__ = "0.0.0"
11
+
12
+ __all__ = [
13
+ "CloudflareChatRetryPolicy",
14
+ "CloudflareWorkersAIModel",
15
+ "CloudflareWorkersAIToolModel",
16
+ ]
@@ -0,0 +1,29 @@
1
+ """HTTP client composition for Cloudflare Workers AI models."""
2
+
3
+ from swarmauri_core.transports.i_http_client import IHttpClient
4
+ from swarmauri_core.transports.i_http_retry_policy import IHttpRetryPolicy
5
+ from swarmauri_transport_httpx import HttpxClient
6
+ from swarmauri_transport_retry import RetryingHttpClient
7
+
8
+ from .CloudflareChatRetryPolicy import CloudflareChatRetryPolicy
9
+
10
+
11
+ def build_cloudflare_client(
12
+ *,
13
+ base_url: str,
14
+ timeout: float,
15
+ max_attempts: int,
16
+ http_client: IHttpClient | None,
17
+ retry_policy: IHttpRetryPolicy | None,
18
+ ) -> IHttpClient:
19
+ """Build a persistent client while preserving injected ownership."""
20
+ concrete_client = http_client or HttpxClient(
21
+ base_url=base_url,
22
+ timeout=timeout,
23
+ )
24
+ return RetryingHttpClient(
25
+ client=concrete_client,
26
+ policy=retry_policy
27
+ or CloudflareChatRetryPolicy(max_attempts=max(max_attempts, 1)),
28
+ own_client=http_client is None,
29
+ )