arcanist-inference 0.2__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,52 @@
1
+ Metadata-Version: 2.4
2
+ Name: arcanist-inference
3
+ Version: 0.2
4
+ Summary: Workflow inference through Arcanist
5
+ Requires-Python: >=3.11
6
+ Description-Content-Type: text/markdown
7
+ Requires-Dist: httpx<1,>=0.27
8
+
9
+ # Arcanist inference for Python
10
+
11
+ Requires Python 3.11 or later. From the repository root, run
12
+ `python -m pip install ./inference/sdk/python`.
13
+
14
+ ```python
15
+ import asyncio
16
+ import os
17
+
18
+ from arcanist_inference import Arcanist
19
+
20
+ async def main():
21
+ async with Arcanist(os.environ["ARCANIST_ROUTING_API_KEY"]) as client:
22
+ with client.workflow("support-reply"):
23
+ response = await client.responses.create(input="Draft a reply.")
24
+ history = [{"role": "user", "content": "Draft a reply."}, *response["output"]]
25
+ async with await client.responses.create(input=history, stream=True) as events:
26
+ async for event in events:
27
+ if event["type"] == "response.output_text.delta":
28
+ print(event["delta"], end="")
29
+
30
+ asyncio.run(main())
31
+ ```
32
+
33
+ Pass `workflow_id` on individual calls or wrap the calling code with
34
+ `client.workflow(name)`. Each entry starts a run. Awaited calls and child tasks
35
+ inherit that run. To continue a run in another process, send
36
+ `client.export_context()` through a trusted channel and use
37
+ `with client.with_parent(carrier):` at the receiving end.
38
+
39
+ The default origin is `https://inference.tryarcanist.com`. Set `base_url`
40
+ to use another origin. Pass `preferred_model="openai/…"` to request a route.
41
+ Pass Responses fields such as `tools`, `reasoning`, and `max_output_tokens`
42
+ as keyword arguments. Preserve complete output items when replaying history.
43
+
44
+ A stream supports one iteration. Its async context closes the connection on
45
+ early exit. Cancel the calling task to interrupt an in-flight request.
46
+ Provider failure events are yielded. A premature EOF raises `RuntimeError`.
47
+ HTTP failures raise `ApiError` with `status`, `code`, and `request_id`.
48
+
49
+ `await client.responses.forward(workflow_id="support-reply", body=payload)`
50
+ returns an HTTPX response with its original status and streaming body.
51
+ Pass `operation="compact"` for compaction. Use `await response.aread()` or
52
+ `response.aiter_bytes()` to read it and `await response.aclose()` when finished.
@@ -0,0 +1,44 @@
1
+ # Arcanist inference for Python
2
+
3
+ Requires Python 3.11 or later. From the repository root, run
4
+ `python -m pip install ./inference/sdk/python`.
5
+
6
+ ```python
7
+ import asyncio
8
+ import os
9
+
10
+ from arcanist_inference import Arcanist
11
+
12
+ async def main():
13
+ async with Arcanist(os.environ["ARCANIST_ROUTING_API_KEY"]) as client:
14
+ with client.workflow("support-reply"):
15
+ response = await client.responses.create(input="Draft a reply.")
16
+ history = [{"role": "user", "content": "Draft a reply."}, *response["output"]]
17
+ async with await client.responses.create(input=history, stream=True) as events:
18
+ async for event in events:
19
+ if event["type"] == "response.output_text.delta":
20
+ print(event["delta"], end="")
21
+
22
+ asyncio.run(main())
23
+ ```
24
+
25
+ Pass `workflow_id` on individual calls or wrap the calling code with
26
+ `client.workflow(name)`. Each entry starts a run. Awaited calls and child tasks
27
+ inherit that run. To continue a run in another process, send
28
+ `client.export_context()` through a trusted channel and use
29
+ `with client.with_parent(carrier):` at the receiving end.
30
+
31
+ The default origin is `https://inference.tryarcanist.com`. Set `base_url`
32
+ to use another origin. Pass `preferred_model="openai/…"` to request a route.
33
+ Pass Responses fields such as `tools`, `reasoning`, and `max_output_tokens`
34
+ as keyword arguments. Preserve complete output items when replaying history.
35
+
36
+ A stream supports one iteration. Its async context closes the connection on
37
+ early exit. Cancel the calling task to interrupt an in-flight request.
38
+ Provider failure events are yielded. A premature EOF raises `RuntimeError`.
39
+ HTTP failures raise `ApiError` with `status`, `code`, and `request_id`.
40
+
41
+ `await client.responses.forward(workflow_id="support-reply", body=payload)`
42
+ returns an HTTPX response with its original status and streaming body.
43
+ Pass `operation="compact"` for compaction. Use `await response.aread()` or
44
+ `response.aiter_bytes()` to read it and `await response.aclose()` when finished.
@@ -0,0 +1,22 @@
1
+ from .client import ApiError, Arcanist
2
+ from .stream import ResponseStream
3
+ from .types import (
4
+ InferenceResponse,
5
+ InputItem,
6
+ Json,
7
+ Provider,
8
+ ResponseEvent,
9
+ ResponseOptions,
10
+ )
11
+
12
+ __all__ = [
13
+ "ApiError",
14
+ "Arcanist",
15
+ "InferenceResponse",
16
+ "InputItem",
17
+ "Json",
18
+ "Provider",
19
+ "ResponseEvent",
20
+ "ResponseOptions",
21
+ "ResponseStream",
22
+ ]
@@ -0,0 +1,149 @@
1
+ import json
2
+ from collections.abc import Mapping
3
+ from contextlib import AbstractAsyncContextManager
4
+ from typing import Literal, Unpack, cast, overload
5
+
6
+ import httpx
7
+
8
+ from .context import WorkflowContext
9
+ from .stream import ResponseStream
10
+ from .types import InferenceResponse, InputItem, Json, ResponseOptions
11
+
12
+
13
+ class ApiError(Exception):
14
+ def __init__(self, response: httpx.Response):
15
+ try:
16
+ body = response.json()
17
+ except ValueError:
18
+ body = None
19
+ error = body.get("error") if isinstance(body, dict) else None
20
+ error = error if isinstance(error, dict) else {}
21
+ self.status = response.status_code
22
+ self.request_id = response.headers.get("x-arcanist-request-id")
23
+ self.code = error.get("code") if isinstance(error.get("code"), str) else None
24
+ message = error.get("message")
25
+ super().__init__(
26
+ message
27
+ if isinstance(message, str)
28
+ else f"Inference request failed ({self.status})"
29
+ )
30
+
31
+
32
+ class Responses:
33
+ def __init__(
34
+ self, client: httpx.AsyncClient, api_key: str, context: WorkflowContext
35
+ ):
36
+ self._client = client
37
+ self._api_key = api_key
38
+ self._context = context
39
+
40
+ async def forward(
41
+ self,
42
+ *,
43
+ body: Json,
44
+ workflow_id: str | None = None,
45
+ preferred_model: str | None = None,
46
+ operation: Literal["responses", "compact"] = "responses",
47
+ headers: Mapping[str, str] | None = None,
48
+ ) -> httpx.Response:
49
+ outgoing = httpx.Headers(headers)
50
+ outgoing.update(
51
+ {
52
+ "authorization": f"Bearer {self._api_key}",
53
+ "content-type": "application/json",
54
+ }
55
+ )
56
+ self._context.apply(outgoing, workflow_id)
57
+ outgoing.pop("x-arcanist-preferred-model", None)
58
+ if preferred_model:
59
+ outgoing["x-arcanist-preferred-model"] = preferred_model
60
+ path = "v1/responses/compact" if operation == "compact" else "v1/responses"
61
+ request = self._client.build_request(
62
+ "POST",
63
+ path,
64
+ content=json.dumps(body, allow_nan=False).encode(),
65
+ headers=outgoing,
66
+ )
67
+ return await self._client.send(request, stream=True)
68
+
69
+ @overload
70
+ async def create(
71
+ self,
72
+ *,
73
+ input: str | list[InputItem],
74
+ stream: Literal[False] = False,
75
+ workflow_id: str | None = None,
76
+ preferred_model: str | None = None,
77
+ headers: Mapping[str, str] | None = None,
78
+ **options: Unpack[ResponseOptions],
79
+ ) -> InferenceResponse: ...
80
+
81
+ @overload
82
+ async def create(
83
+ self,
84
+ *,
85
+ input: str | list[InputItem],
86
+ stream: Literal[True],
87
+ workflow_id: str | None = None,
88
+ preferred_model: str | None = None,
89
+ headers: Mapping[str, str] | None = None,
90
+ **options: Unpack[ResponseOptions],
91
+ ) -> ResponseStream: ...
92
+
93
+ async def create(
94
+ self,
95
+ *,
96
+ input: str | list[InputItem],
97
+ stream: bool | None = None,
98
+ workflow_id: str | None = None,
99
+ preferred_model: str | None = None,
100
+ headers: Mapping[str, str] | None = None,
101
+ **options: Unpack[ResponseOptions],
102
+ ) -> InferenceResponse | ResponseStream:
103
+ body = dict(options, input=input)
104
+ if stream is not None:
105
+ body["stream"] = stream
106
+ response = await self.forward(
107
+ body=cast(Json, body),
108
+ workflow_id=workflow_id,
109
+ preferred_model=preferred_model,
110
+ headers=headers,
111
+ )
112
+ keep_open = False
113
+ try:
114
+ if not response.is_success:
115
+ await response.aread()
116
+ raise ApiError(response)
117
+ if stream:
118
+ if not response.headers.get("content-type", "").startswith(
119
+ "text/event-stream"
120
+ ):
121
+ raise ValueError("Expected an inference event stream")
122
+ keep_open = True
123
+ return ResponseStream(response)
124
+ await response.aread()
125
+ return response.json()
126
+ finally:
127
+ if not keep_open:
128
+ await response.aclose()
129
+
130
+
131
+ class Arcanist(WorkflowContext, AbstractAsyncContextManager):
132
+ def __init__(
133
+ self,
134
+ api_key: str,
135
+ *,
136
+ base_url: str = "https://inference.tryarcanist.com",
137
+ transport: httpx.AsyncBaseTransport | None = None,
138
+ ):
139
+ super().__init__()
140
+ self._http = httpx.AsyncClient(
141
+ base_url=base_url, transport=transport, timeout=None, follow_redirects=False
142
+ )
143
+ self.responses = Responses(self._http, api_key, self)
144
+
145
+ async def aclose(self):
146
+ await self._http.aclose()
147
+
148
+ async def __aexit__(self, *exc):
149
+ await self.aclose()
@@ -0,0 +1,72 @@
1
+ import re
2
+ import secrets
3
+ from collections.abc import Iterator, Mapping
4
+ from contextlib import contextmanager
5
+ from contextvars import ContextVar
6
+
7
+ import httpx
8
+
9
+
10
+ class WorkflowContext:
11
+ def __init__(self):
12
+ self._active = ContextVar[dict[str, str]]("arcanist_workflow", default={})
13
+
14
+ def export_context(self) -> dict[str, str]:
15
+ return self._active.get().copy()
16
+
17
+ @contextmanager
18
+ def workflow(self, workflow_id: str) -> Iterator[None]:
19
+ if not workflow_id.strip():
20
+ raise ValueError("workflow_id is required")
21
+ run_id = secrets.token_hex(8)
22
+ traceparent = (
23
+ self._active.get().get("traceparent")
24
+ or f"00-{secrets.token_hex(16)}-{run_id}-01"
25
+ )
26
+ with self.with_parent(
27
+ {
28
+ "traceparent": traceparent,
29
+ "x-arcanist-workflow-id": workflow_id,
30
+ "x-arcanist-workflow-run-id": run_id,
31
+ }
32
+ ):
33
+ yield
34
+
35
+ @contextmanager
36
+ def with_parent(self, carrier: Mapping[str, str]) -> Iterator[None]:
37
+ headers = httpx.Headers(carrier)
38
+ traceparent = headers.get("traceparent", "")
39
+ match = re.fullmatch(
40
+ r"00-([0-9a-f]{32})-([0-9a-f]{16})-[0-9a-f]{2}", traceparent
41
+ )
42
+ context = {}
43
+ if match and all(int(group, 16) for group in match.groups()):
44
+ context["traceparent"] = traceparent
45
+ workflow = headers.get("x-arcanist-workflow-id")
46
+ run = headers.get("x-arcanist-workflow-run-id", "")
47
+ if workflow and re.fullmatch(r"[0-9a-f]{16}", run) and int(run, 16):
48
+ context.update(
49
+ {
50
+ "x-arcanist-workflow-id": workflow,
51
+ "x-arcanist-workflow-run-id": run,
52
+ }
53
+ )
54
+ token = self._active.set(context)
55
+ try:
56
+ yield
57
+ finally:
58
+ self._active.reset(token)
59
+
60
+ def apply(self, headers: httpx.Headers, workflow_id: str | None):
61
+ context = self._active.get()
62
+ active_id = context.get("x-arcanist-workflow-id")
63
+ workflow_id = active_id if workflow_id is None else workflow_id
64
+ if not workflow_id:
65
+ raise ValueError("Specify workflow_id or call inside a workflow")
66
+ if active_id and workflow_id != active_id:
67
+ raise ValueError("Start a nested workflow to change the active workflow ID")
68
+ headers["x-arcanist-workflow-id"] = workflow_id
69
+ if context:
70
+ headers.pop("x-arcanist-workflow-run-id", None)
71
+ headers.update(context)
72
+ headers["x-arcanist-call-id"] = secrets.token_hex(8)
File without changes
@@ -0,0 +1,65 @@
1
+ import json
2
+ from typing import cast
3
+ from collections.abc import AsyncIterator
4
+ from contextlib import AbstractAsyncContextManager
5
+
6
+ import httpx
7
+
8
+ from .types import ResponseEvent
9
+
10
+
11
+ class ResponseStream(AbstractAsyncContextManager):
12
+ def __init__(self, response: httpx.Response):
13
+ self._response = response
14
+ self._consumed = False
15
+
16
+ async def aclose(self):
17
+ await self._response.aclose()
18
+
19
+ async def __aexit__(self, *exc):
20
+ await self.aclose()
21
+
22
+ async def __aiter__(self) -> AsyncIterator[ResponseEvent]:
23
+ if self._consumed:
24
+ raise RuntimeError("Response stream has already been consumed")
25
+ self._consumed = True
26
+ data = []
27
+ try:
28
+ async for line in self._lines():
29
+ if line == "data" or line.startswith("data:"):
30
+ data.append(line[5:].removeprefix(" "))
31
+ elif not line and data:
32
+ value = "\n".join(data)
33
+ data.clear()
34
+ if value == "[DONE]":
35
+ continue
36
+ event = json.loads(value)
37
+ if not isinstance(event, dict) or not isinstance(
38
+ event.get("type"), str
39
+ ):
40
+ raise ValueError("Invalid inference stream event")
41
+ if event["type"] in {
42
+ "response.completed",
43
+ "response.incomplete",
44
+ "response.failed",
45
+ "error",
46
+ }:
47
+ await self.aclose()
48
+ yield cast(ResponseEvent, event)
49
+ return
50
+ yield cast(ResponseEvent, event)
51
+ raise RuntimeError("Stream ended without a provider completion")
52
+ finally:
53
+ await self.aclose()
54
+
55
+ async def _lines(self) -> AsyncIterator[str]:
56
+ buffer = bytearray()
57
+ async for chunk in self._response.aiter_bytes():
58
+ lines = chunk.split(b"\n")
59
+ buffer.extend(lines[0])
60
+ if len(lines) > 1:
61
+ yield buffer.rstrip(b"\r").decode("utf-8")
62
+ buffer.clear()
63
+ for line in lines[1:-1]:
64
+ yield line.rstrip(b"\r").decode("utf-8")
65
+ buffer.extend(lines[-1])
@@ -0,0 +1,44 @@
1
+ from typing import Literal, NotRequired, Required, TypedDict
2
+
3
+ Json = None | bool | int | float | str | list["Json"] | dict[str, "Json"]
4
+ InputItem = dict[str, Json]
5
+ Provider = Literal["openai", "anthropic", "baseten"]
6
+
7
+
8
+ class FunctionTool(TypedDict, total=False):
9
+ type: Required[Literal["function"]]
10
+ name: Required[str]
11
+ parameters: Required[Json]
12
+ description: str
13
+ strict: bool
14
+
15
+
16
+ class FunctionChoice(TypedDict):
17
+ type: Literal["function"]
18
+ name: str
19
+
20
+
21
+ class ResponseOptions(TypedDict, total=False):
22
+ instructions: str
23
+ max_output_tokens: int
24
+ temperature: float
25
+ top_p: float
26
+ reasoning: dict[str, int | str]
27
+ tools: list[FunctionTool]
28
+ tool_choice: Literal["auto", "none", "required"] | FunctionChoice
29
+ store: Literal[False]
30
+
31
+
32
+ class InferenceResponse(TypedDict):
33
+ id: str
34
+ object: Literal["response"]
35
+ status: Literal["completed", "incomplete", "failed", "in_progress"]
36
+ output: list[InputItem]
37
+ model: NotRequired[str]
38
+ usage: NotRequired[dict[str, Json]]
39
+
40
+
41
+ class ResponseEvent(TypedDict):
42
+ type: str
43
+ delta: NotRequired[str]
44
+ response: NotRequired[InferenceResponse]
@@ -0,0 +1,52 @@
1
+ Metadata-Version: 2.4
2
+ Name: arcanist-inference
3
+ Version: 0.2
4
+ Summary: Workflow inference through Arcanist
5
+ Requires-Python: >=3.11
6
+ Description-Content-Type: text/markdown
7
+ Requires-Dist: httpx<1,>=0.27
8
+
9
+ # Arcanist inference for Python
10
+
11
+ Requires Python 3.11 or later. From the repository root, run
12
+ `python -m pip install ./inference/sdk/python`.
13
+
14
+ ```python
15
+ import asyncio
16
+ import os
17
+
18
+ from arcanist_inference import Arcanist
19
+
20
+ async def main():
21
+ async with Arcanist(os.environ["ARCANIST_ROUTING_API_KEY"]) as client:
22
+ with client.workflow("support-reply"):
23
+ response = await client.responses.create(input="Draft a reply.")
24
+ history = [{"role": "user", "content": "Draft a reply."}, *response["output"]]
25
+ async with await client.responses.create(input=history, stream=True) as events:
26
+ async for event in events:
27
+ if event["type"] == "response.output_text.delta":
28
+ print(event["delta"], end="")
29
+
30
+ asyncio.run(main())
31
+ ```
32
+
33
+ Pass `workflow_id` on individual calls or wrap the calling code with
34
+ `client.workflow(name)`. Each entry starts a run. Awaited calls and child tasks
35
+ inherit that run. To continue a run in another process, send
36
+ `client.export_context()` through a trusted channel and use
37
+ `with client.with_parent(carrier):` at the receiving end.
38
+
39
+ The default origin is `https://inference.tryarcanist.com`. Set `base_url`
40
+ to use another origin. Pass `preferred_model="openai/…"` to request a route.
41
+ Pass Responses fields such as `tools`, `reasoning`, and `max_output_tokens`
42
+ as keyword arguments. Preserve complete output items when replaying history.
43
+
44
+ A stream supports one iteration. Its async context closes the connection on
45
+ early exit. Cancel the calling task to interrupt an in-flight request.
46
+ Provider failure events are yielded. A premature EOF raises `RuntimeError`.
47
+ HTTP failures raise `ApiError` with `status`, `code`, and `request_id`.
48
+
49
+ `await client.responses.forward(workflow_id="support-reply", body=payload)`
50
+ returns an HTTPX response with its original status and streaming body.
51
+ Pass `operation="compact"` for compaction. Use `await response.aread()` or
52
+ `response.aiter_bytes()` to read it and `await response.aclose()` when finished.
@@ -0,0 +1,14 @@
1
+ README.md
2
+ pyproject.toml
3
+ arcanist_inference/VERSION
4
+ arcanist_inference/__init__.py
5
+ arcanist_inference/client.py
6
+ arcanist_inference/context.py
7
+ arcanist_inference/py.typed
8
+ arcanist_inference/stream.py
9
+ arcanist_inference/types.py
10
+ arcanist_inference.egg-info/PKG-INFO
11
+ arcanist_inference.egg-info/SOURCES.txt
12
+ arcanist_inference.egg-info/dependency_links.txt
13
+ arcanist_inference.egg-info/requires.txt
14
+ arcanist_inference.egg-info/top_level.txt
@@ -0,0 +1 @@
1
+ httpx<1,>=0.27
@@ -0,0 +1 @@
1
+ arcanist_inference
@@ -0,0 +1,17 @@
1
+ [build-system]
2
+ requires = ["setuptools>=66"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "arcanist-inference"
7
+ dynamic = ["version"]
8
+ description = "Workflow inference through Arcanist"
9
+ readme = "README.md"
10
+ requires-python = ">=3.11"
11
+ dependencies = ["httpx>=0.27,<1"]
12
+
13
+ [tool.setuptools.dynamic]
14
+ version = {file = "arcanist_inference/VERSION"}
15
+
16
+ [tool.setuptools.package-data]
17
+ arcanist_inference = ["VERSION", "py.typed"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+