factorial-compute 0.0.1__tar.gz

factorial_compute-0.0.1/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.4
+Name: factorial-compute
+Version: 0.0.1
+Summary: Typed answers from AI compute: images, masks, transcripts and text, whichever model or supplier produced them.
+Project-URL: Homepage, https://factorialcompute.com
+Project-URL: Repository, https://github.com/prateekvjoshi/factorial-compute
+Keywords: ai,inference,api,segmentation,transcription,image-generation
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27
+
+# factorial-compute
+
+One API for AI compute that returns **typed answers** — an image, a set of
+masks, a transcript, text — in the same shape whichever model or supplier
+produced it.
+
+```bash
+pip install factorial-compute
+export FACTORIAL_API_KEY=fc_...
+```
+
+```python
+from factorial_compute import Client
+
+f = Client()  # reads FACTORIAL_API_KEY
+
+# Text, and JSON on request.
+print(f.run(model="gpt-oss-120b", input="Name three uses for a forklift.").text)
+
+# An image from a prompt.
+result = f.run(model="flux-schnell", input={"prompt": "a red forklift in a warehouse"})
+result.images[0].save("forklift.jpg")
+
+# Masks: one per object, each with a box measured from the mask.
+result = f.run(model="sam2-segment", input={
+    "image": "warehouse.jpg",                      # a local path: uploaded for you
+    "objects": [{"id": "pallet", "box": [40, 60, 300, 280]},
+                {"id": "cone", "point": [512, 240]}],
+})
+for mask in result.masks:
+    print(mask.id, mask.box)
+    mask.save(f"{mask.id}.png")
+
+# A transcript, with timestamps.
+result = f.run(model="whisper", input={"audio": "meeting.mp3"})
+print(result.transcript.text)
+for segment in result.transcript.segments:
+    print(f"{segment.start:6.1f}s  {segment.text}")
+```
+
+That is the whole surface for most work: `run()` with a model id and an
+`input`, then read the typed answer.
+
+## Rules worth knowing
+
+- **Files go in by path, URL or bytes** under the keys `image`, `images`,
+  `audio` and `video`. The client uploads them and sends a reference. (A chat
+  model that reads images takes them as URLs, sent as written.)
+- **Answers are typed.** `.text`, `.images`, `.masks`, `.transcript`. Asking a
+  result for the wrong kind raises, rather than returning something empty.
+- **Files come back as handles.** `.save(path)` writes one; `.read()` returns
+  the bytes. They stay on the server until you ask.
+- **Retries are safe.** Every `run()` carries an idempotency key and is retried
+  on connection failures and on 429/502/503/504, so a retry never runs — or
+  bills — the work twice.
+- **Errors say what to change.** A refused input raises `InvalidInput` whose
+  message names the field and a value that works.
+- **Usage is in the model's own unit**: tokens, `images`, `audio_seconds`.
+  `result.usage.units` has it.
+
+## Which models exist
+
+```python
+for model in f.models.catalog():
+    print(model["id"], model.get("output"), model["unit"])
+```
+
+`output` says what kind of answer a model returns — `image`, `masks`,
+`transcript` — so code can pick a model by what it produces.
+
+## Longer work
+
+```python
+handle = f.submit(model="flux-schnell", input={"prompt": "..."})
+result = handle.wait()
+```
+
+`submit` returns before the work runs and survives your process exiting.

factorial_compute-0.0.1/README.md

@@ -0,0 +1,78 @@
+# factorial-compute
+
+One API for AI compute that returns **typed answers** — an image, a set of
+masks, a transcript, text — in the same shape whichever model or supplier
+produced it.
+
+```bash
+pip install factorial-compute
+export FACTORIAL_API_KEY=fc_...
+```
+
+```python
+from factorial_compute import Client
+
+f = Client()  # reads FACTORIAL_API_KEY
+
+# Text, and JSON on request.
+print(f.run(model="gpt-oss-120b", input="Name three uses for a forklift.").text)
+
+# An image from a prompt.
+result = f.run(model="flux-schnell", input={"prompt": "a red forklift in a warehouse"})
+result.images[0].save("forklift.jpg")
+
+# Masks: one per object, each with a box measured from the mask.
+result = f.run(model="sam2-segment", input={
+    "image": "warehouse.jpg",                      # a local path: uploaded for you
+    "objects": [{"id": "pallet", "box": [40, 60, 300, 280]},
+                {"id": "cone", "point": [512, 240]}],
+})
+for mask in result.masks:
+    print(mask.id, mask.box)
+    mask.save(f"{mask.id}.png")
+
+# A transcript, with timestamps.
+result = f.run(model="whisper", input={"audio": "meeting.mp3"})
+print(result.transcript.text)
+for segment in result.transcript.segments:
+    print(f"{segment.start:6.1f}s  {segment.text}")
+```
+
+That is the whole surface for most work: `run()` with a model id and an
+`input`, then read the typed answer.
+
+## Rules worth knowing
+
+- **Files go in by path, URL or bytes** under the keys `image`, `images`,
+  `audio` and `video`. The client uploads them and sends a reference. (A chat
+  model that reads images takes them as URLs, sent as written.)
+- **Answers are typed.** `.text`, `.images`, `.masks`, `.transcript`. Asking a
+  result for the wrong kind raises, rather than returning something empty.
+- **Files come back as handles.** `.save(path)` writes one; `.read()` returns
+  the bytes. They stay on the server until you ask.
+- **Retries are safe.** Every `run()` carries an idempotency key and is retried
+  on connection failures and on 429/502/503/504, so a retry never runs — or
+  bills — the work twice.
+- **Errors say what to change.** A refused input raises `InvalidInput` whose
+  message names the field and a value that works.
+- **Usage is in the model's own unit**: tokens, `images`, `audio_seconds`.
+  `result.usage.units` has it.
+
+## Which models exist
+
+```python
+for model in f.models.catalog():
+    print(model["id"], model.get("output"), model["unit"])
+```
+
+`output` says what kind of answer a model returns — `image`, `masks`,
+`transcript` — so code can pick a model by what it produces.
+
+## Longer work
+
+```python
+handle = f.submit(model="flux-schnell", input={"prompt": "..."})
+result = handle.wait()
+```
+
+`submit` returns before the work runs and survives your process exiting.

factorial_compute-0.0.1/factorial_compute/__init__.py

@@ -0,0 +1,78 @@
+"""The Python client.
+
+    from factorial_compute import Client
+
+    f = Client()
+    print(f.run(model="assistant", input="Explain Euler's identity.").text)
+
+The package name and every customer-visible string live in `_branding.py`, so
+renaming the product is one file rather than a search across a client people
+have already installed.
+"""
+
+from ._branding import ENV_API_KEY, ENV_BASE_URL, PRODUCT
+from .client import Client
+from .errors import (
+    AccountSuspended,
+    AuthenticationError,
+    BudgetExceeded,
+    CapacityUnavailable,
+    ExecutionFailed,
+    FactorialError,
+    InvalidInput,
+    ModelNotSupported,
+    NotDeployed,
+    NotFound,
+    PermissionDenied,
+    RateLimited,
+    Timeout,
+)
+from .outputs import Artifact, Image, Mask, Masks, Segment, Transcript
+from .types import (
+    Batch,
+    Event,
+    Execution,
+    ModelInfo,
+    Result,
+    Session,
+    Timing,
+    Usage,
+    UsageReport,
+)
+
+__version__ = "0.0.1"
+
+__all__ = [
+    "ENV_API_KEY",
+    "ENV_BASE_URL",
+    "PRODUCT",
+    "AccountSuspended",
+    "Artifact",
+    "AuthenticationError",
+    "Batch",
+    "BudgetExceeded",
+    "CapacityUnavailable",
+    "Client",
+    "Event",
+    "Execution",
+    "ExecutionFailed",
+    "FactorialError",
+    "Image",
+    "InvalidInput",
+    "Mask",
+    "Masks",
+    "ModelInfo",
+    "ModelNotSupported",
+    "NotDeployed",
+    "NotFound",
+    "PermissionDenied",
+    "RateLimited",
+    "Result",
+    "Segment",
+    "Session",
+    "Timeout",
+    "Timing",
+    "Transcript",
+    "Usage",
+    "UsageReport",
+]

factorial_compute-0.0.1/factorial_compute/_branding.py

@@ -0,0 +1,39 @@
+"""Everything the product's name touches, in one place.
+
+The name has changed once and could change again, and every string below moves
+with it: the environment variable a customer exports, the prefix on their key,
+the header they set, and the sentence in every error. Collecting them here
+makes that a one-file change rather than a search across a client people have
+already installed.
+
+These deliberately duplicate constants that also exist on the server, because
+the client is its own distribution and must not import the platform to send a
+request. Duplication across that boundary is the price of the boundary; what
+makes it safe is that `tests/test_structural_invariants.py` asserts the two
+sides agree. A key prefix that matched on one side and not the other would
+reject every key with a message about the key being malformed.
+
+`KEY_PREFIXES` is a tuple rather than a string on purpose. A rename can issue
+new keys under a new prefix while the ones already sitting in customers'
+`.env` files keep working - which matters most for the earliest users, who are
+the ones you least want to send a "please rotate your key" email to. It holds
+one entry today because no key was ever issued under the old name.
+"""
+
+from __future__ import annotations
+
+# What the product is called in a sentence: "cannot reach Factorial at ...".
+PRODUCT = "Factorial"
+ENV_API_KEY = "FACTORIAL_API_KEY"
+ENV_BASE_URL = "FACTORIAL_BASE_URL"
+KEY_PREFIXES = ("fc_",)
+TAGS_HEADER = "X-Factorial-Tags"
+# Production, because this package is what a customer pip-installs and they
+# have no localhost to talk to. Anyone running the server themselves sets
+# FACTORIAL_BASE_URL, and the connection error names the URL it tried so a
+# forgotten override is one line to diagnose rather than a mystery.
+DEFAULT_BASE_URL = "https://api.factorialcompute.com"
+# Lowercase and hyphenated, which is the convention for a User-Agent token and
+# is not the same string as PRODUCT above - hence spelled out rather than
+# interpolated from it.
+USER_AGENT = "factorial-compute-python/0.0.1"