|
1 | | -# interfaze-python |
2 | | -Interfaze AI SDK for Python |
| 1 | +# interfaze |
| 2 | + |
| 3 | +The official [Interfaze](https://interfaze.ai) SDK for Python — a thin, typed wrapper over the |
| 4 | +OpenAI SDK. Same `chat.completions` surface, plus typed access to everything Interfaze adds |
| 5 | +(`precontext`, `reasoning`, `vcache`, `task`/`guard` helpers). Sync and async. |
| 6 | + |
| 7 | +## Install |
| 8 | + |
| 9 | +```bash |
| 10 | +pip install interfaze |
| 11 | +export INTERFAZE_API_KEY="sk_..." |
| 12 | +``` |
| 13 | + |
| 14 | +## Quickstart |
| 15 | + |
| 16 | +```python |
| 17 | +from interfaze import Interfaze |
| 18 | + |
| 19 | +interfaze = Interfaze() # reads INTERFAZE_API_KEY |
| 20 | + |
| 21 | +res = interfaze.chat.completions.create( |
| 22 | + messages=[{"role": "user", "content": "Write a haiku about deterministic AI."}], |
| 23 | +) |
| 24 | +print(res.choices[0].message.content) |
| 25 | +print("cache hit:", res.vcache) # typed Interfaze extra |
| 26 | +``` |
| 27 | + |
| 28 | +Async: |
| 29 | + |
| 30 | +```python |
| 31 | +from interfaze import AsyncInterfaze |
| 32 | + |
| 33 | +interfaze = AsyncInterfaze() |
| 34 | +res = await interfaze.chat.completions.create(messages=[{"role": "user", "content": "Hello"}]) |
| 35 | +``` |
| 36 | + |
| 37 | +## Task helpers |
| 38 | + |
| 39 | +```python |
| 40 | +interfaze.tasks.ocr("https://example.com/receipt.jpg") |
| 41 | +interfaze.tasks.web_search("latest AI agent news") |
| 42 | +interfaze.tasks.transcribe("https://example.com/audio.wav") |
| 43 | +interfaze.tasks.scrape("https://example.com/product") |
| 44 | +interfaze.tasks.translate("Hello", to="French") |
| 45 | +interfaze.tasks.object_detection("https://example.com/photo.jpg") |
| 46 | +interfaze.tasks.gui_detection("https://example.com/screenshot.png") |
| 47 | +interfaze.tasks.forecast("https://example.com/series.csv", periods=30) |
| 48 | +``` |
| 49 | + |
| 50 | +Or force a task on a raw completion: |
| 51 | + |
| 52 | +```python |
| 53 | +from interfaze import inputs |
| 54 | + |
| 55 | +res = interfaze.chat.completions.create( |
| 56 | + task="ocr", |
| 57 | + messages=[{"role": "user", "content": [ |
| 58 | + {"type": "text", "text": "Extract the total"}, |
| 59 | + inputs.file("https://example.com/receipt.jpg"), |
| 60 | + ]}], |
| 61 | +) |
| 62 | +``` |
| 63 | + |
| 64 | +## Structured output |
| 65 | + |
| 66 | +```python |
| 67 | +from interfaze import response_format |
| 68 | + |
| 69 | +res = interfaze.chat.completions.create( |
| 70 | + messages=[{"role": "user", "content": "Weather in Tokyo?"}], |
| 71 | + response_format=response_format({ |
| 72 | + "type": "object", |
| 73 | + "properties": {"city": {"type": "string"}, "temp_c": {"type": "number"}}, |
| 74 | + "required": ["city", "temp_c"], |
| 75 | + }), |
| 76 | +) |
| 77 | +``` |
| 78 | + |
| 79 | +## Streaming |
| 80 | + |
| 81 | +```python |
| 82 | +stream = interfaze.chat.completions.stream( |
| 83 | + messages=[{"role": "user", "content": "Tell me a story."}], |
| 84 | +) |
| 85 | +for chunk in stream: |
| 86 | + print(chunk.choices[0].delta.content or "", end="") |
| 87 | +final = stream.get_final_completion() |
| 88 | +print(final.reasoning, final.precontext) |
| 89 | +``` |
| 90 | + |
| 91 | +> Plain `create(stream=True)` also works and returns the raw chunk iterator; `.stream()` adds |
| 92 | +> accumulation and surfaces `reasoning`/`precontext`. |
| 93 | +
|
| 94 | +## Inputs |
| 95 | + |
| 96 | +```python |
| 97 | +from interfaze import inputs |
| 98 | + |
| 99 | +inputs.image("https://…/a.png") # image_url part |
| 100 | +inputs.file("https://…/doc.pdf") # file part (pdf/csv/xml/json/text/video…) |
| 101 | +inputs.audio("https://…/a.wav") # input_audio part |
| 102 | +inputs.data_url(raw_bytes, "image/png") # base64 data URI |
| 103 | +inputs.from_path("./doc.pdf") # read a local file |
| 104 | +``` |
| 105 | + |
| 106 | +URLs and base64 work; raw `bytes` do **not** (must be base64-encoded — this SDK does it for you via |
| 107 | +`data_url`/`from_path`). `image/gif` and `image/avif` are rejected client-side. |
| 108 | + |
| 109 | +## Interfaze extras |
| 110 | + |
| 111 | +- `res.precontext` — raw outputs of internal tools that ran (OCR/web/scrape/STT/forecast/…). |
| 112 | +- `res.reasoning` — reasoning text (with `reasoning_effort="high"` and no schema). |
| 113 | +- `res.vcache` — whether the semantic cache was hit. |
| 114 | +- `reasoning_effort` accepts `"on"`/`"off"`/`"auto"` in addition to `minimal|low|medium|high`. |
| 115 | +- Guardrails: `create(guard=["S1", "S12_IMAGE"], …)`. |
| 116 | +- Control options: `Interfaze(show_additional_info=..., bypass_moe=..., bypass_cache=..., admin_key=...)`. |
| 117 | +- Custom params: pass `extra_body={...}` / `extra_headers={...}` straight through to the request. |
| 118 | + |
| 119 | +## Good to know |
| 120 | + |
| 121 | +- Interfaze implements `chat.completions` and `models`; other OpenAI endpoints are not exposed. |
| 122 | +- `temperature` ≤ 1, `max_tokens` ≤ 32000, `top_p` ≤ 1 (above → 400). Use `max_tokens` (not |
| 123 | + `max_completion_tokens`) to bound output. |
| 124 | +- `n`, `seed`, `stop`, penalties, `logprobs`, `tool_choice`, `top_k` are ignored by Interfaze. |
| 125 | +- The underlying OpenAI client is available at `interfaze.openai`. |
| 126 | + |
| 127 | +## License |
| 128 | + |
| 129 | +MIT |
0 commit comments