interhumanai 1.2.2__tar.gz → 1.3.0__tar.gz

{interhumanai-1.2.2 → interhumanai-1.3.0}/CHANGELOG.md

@@ -5,6 +5,22 @@ All notable changes to `interhumanai` are documented here. The package follows
 the TypeScript SDK (`@interhumanai/sdk`): both packages always carry the same
 version and release together.
 
+## 1.3.0
+
+- Added the whole-file signal list to upload jobs. ``submit(include=...)``
+  now takes ``UploadJobIncludeFlag``: the two ``IncludeFlag`` Conversation
+  Quality Index values plus ``SIGNALS`` (``IncludeFlag`` members still work).
+  With ``SIGNALS``, a completed job's ``UploadJobResult.signals`` carries every
+  window's signals as one chronological list, same-type signals in adjacent
+  windows merged into one span that keeps the highest probability and its
+  rationale, with no ``modality``. ``None`` without the flag; an empty list
+  when requested and nothing was detected. The ``windows`` are unchanged.
+
+## 1.2.3
+
+- Revised the reference documentation for authentication. Documentation only;
+  no behavior change.
+
 ## 1.2.2
 
 - Corrected the reference docs for ``SessionConfigOptions.model``: it lists the models the

{interhumanai-1.2.2 → interhumanai-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: interhumanai
-Version: 1.2.2
+Version: 1.3.0
 Summary: First-party Python SDK for the Interhuman API: upload and stream social-signal analysis.
 Project-URL: Homepage, https://docs.interhuman.ai
 Project-URL: Repository, https://github.com/interhumanai/interhuman-api
@@ -144,12 +144,13 @@ job**: the API validates the file, answers with a job envelope, and analyzes
 the file afterwards. Poll the job until it is `completed` or `failed`:
 
 ```python
-from interhumanai import IncludeFlag, UploadModel
+from interhumanai import UploadJobIncludeFlag, UploadModel
 
 job = await client.upload.submit(
     "meeting.mp4",
     model=UploadModel.INTER_2,
-    include=[IncludeFlag.CONVERSATION_QUALITY_OVERALL],   # optional quality scores
+    # optional whole-file views: quality scores and the merged signal list
+    include=[UploadJobIncludeFlag.CONVERSATION_QUALITY_OVERALL, UploadJobIncludeFlag.SIGNALS],
 )
 print(job.job_id, job.status.value)          # queued
 
@@ -158,6 +159,8 @@ if job.status.value == "completed":
     for window in job.result.windows:
         names = ", ".join(signal.type.value for signal in window.signals)
         print(f"{window.start_seconds:5.1f}s {window.engagement_status.value:11} {names}")
+    for signal in job.result.signals:
+        print(signal.type.value, signal.start, signal.end)
     print(job.result.conversation_quality.overall.quality_index)
 else:
     print(job.error.error_id, job.error.message)
@@ -166,11 +169,15 @@ else:
 - `submit(file, model=..., wait_seconds=0, include=None)` — pass `wait_seconds`
   to let the API hold the request open for up to that long and return the
   finished job inline when it completes in time; otherwise it returns the
-  queued envelope. Pass `include` with the same `IncludeFlag` values `analyze`
-  takes to have the result carry `conversation_quality`, an
-  `UploadJobConversationQuality` scored over the whole file with `overall`
-  and/or `timeline` set for the flags you named; without it the result has no
-  quality block.
+  queued envelope. Pass `include` with `UploadJobIncludeFlag` values to have
+  the result carry whole-file views. The two Conversation Quality Index values
+  (the same ones `analyze` takes as `IncludeFlag`, whose members also work
+  here) add `conversation_quality`, an `UploadJobConversationQuality` scored
+  over the whole file with `overall` and/or `timeline` set for the flags you
+  named. `SIGNALS` adds `signals`: every window's signals as one chronological
+  list, same-type signals in adjacent windows merged into one span with the
+  highest probability and its rationale, and no `modality` (an empty list when
+  nothing was detected). Without a flag the result has no such section.
 - `get_job(job_id)` — one status read. Raises `InterhumanAPIError` with
   `error_id` `ih4021` once the job has expired (`job.expires_at`).
 - `wait_for_job(job_id, timeout=None, poll_interval=2.0)` — returns the

{interhumanai-1.2.2 → interhumanai-1.3.0}/README.md

@@ -118,12 +118,13 @@ job**: the API validates the file, answers with a job envelope, and analyzes
 the file afterwards. Poll the job until it is `completed` or `failed`:
 
 ```python
-from interhumanai import IncludeFlag, UploadModel
+from interhumanai import UploadJobIncludeFlag, UploadModel
 
 job = await client.upload.submit(
     "meeting.mp4",
     model=UploadModel.INTER_2,
-    include=[IncludeFlag.CONVERSATION_QUALITY_OVERALL],   # optional quality scores
+    # optional whole-file views: quality scores and the merged signal list
+    include=[UploadJobIncludeFlag.CONVERSATION_QUALITY_OVERALL, UploadJobIncludeFlag.SIGNALS],
 )
 print(job.job_id, job.status.value)          # queued
 
@@ -132,6 +133,8 @@ if job.status.value == "completed":
     for window in job.result.windows:
         names = ", ".join(signal.type.value for signal in window.signals)
         print(f"{window.start_seconds:5.1f}s {window.engagement_status.value:11} {names}")
+    for signal in job.result.signals:
+        print(signal.type.value, signal.start, signal.end)
     print(job.result.conversation_quality.overall.quality_index)
 else:
     print(job.error.error_id, job.error.message)
@@ -140,11 +143,15 @@ else:
 - `submit(file, model=..., wait_seconds=0, include=None)` — pass `wait_seconds`
   to let the API hold the request open for up to that long and return the
   finished job inline when it completes in time; otherwise it returns the
-  queued envelope. Pass `include` with the same `IncludeFlag` values `analyze`
-  takes to have the result carry `conversation_quality`, an
-  `UploadJobConversationQuality` scored over the whole file with `overall`
-  and/or `timeline` set for the flags you named; without it the result has no
-  quality block.
+  queued envelope. Pass `include` with `UploadJobIncludeFlag` values to have
+  the result carry whole-file views. The two Conversation Quality Index values
+  (the same ones `analyze` takes as `IncludeFlag`, whose members also work
+  here) add `conversation_quality`, an `UploadJobConversationQuality` scored
+  over the whole file with `overall` and/or `timeline` set for the flags you
+  named. `SIGNALS` adds `signals`: every window's signals as one chronological
+  list, same-type signals in adjacent windows merged into one span with the
+  highest probability and its rationale, and no `modality` (an empty list when
+  nothing was detected). Without a flag the result has no such section.
 - `get_job(job_id)` — one status read. Raises `InterhumanAPIError` with
   `error_id` `ih4021` once the job has expired (`job.expires_at`).
 - `wait_for_job(job_id, timeout=None, poll_interval=2.0)` — returns the

{interhumanai-1.2.2 → interhumanai-1.3.0}/src/interhumanai/__init__.py

@@ -113,6 +113,7 @@ from .types import (
     UploadJob,
     UploadJobConversationQuality,
     UploadJobError,
+    UploadJobIncludeFlag,
     UploadJobResult,
     UploadJobSignal,
     UploadJobStatus,
@@ -214,6 +215,7 @@ __all__ = [
     "UploadJob",
     "UploadJobConversationQuality",
     "UploadJobError",
+    "UploadJobIncludeFlag",
     "UploadJobResult",
     "UploadJobSignal",
     "UploadJobStatus",

{interhumanai-1.2.2 → interhumanai-1.3.0}/src/interhumanai/_version.py

@@ -1,3 +1,3 @@
 """Package version (single source of truth, read by hatchling at build time)."""
 
-__version__ = "1.2.2"
+__version__ = "1.3.0"

{interhumanai-1.2.2 → interhumanai-1.3.0}/src/interhumanai/auth.py

@@ -20,7 +20,7 @@ DEFAULT_REFRESH_SKEW_SECONDS = 30.0
 
 
 class TokenResponse(BaseModel):
-    """Response of ``POST /v1/auth``."""
+    """Response of a token request."""
 
     access_token: str
     token_type: str
@@ -48,7 +48,7 @@ def _scope_values(scopes: Sequence[Scope | str]) -> list[str]:
 
 
 class AuthClient:
-    """Client for the token endpoints (``/v1/auth`` and ``/v1/client_tokens``).
+    """Client for the client-token endpoints (``/v1/client_tokens``).
 
     Args:
         environment: Named environment to call. Defaults to ``production``.
@@ -89,7 +89,7 @@ class AuthClient:
         key_secret: str,
         scopes: Sequence[Scope | str],
     ) -> TokenResponse:
-        """Exchange API key credentials for a short-lived bearer access token.
+        """Authenticate with API key credentials for a short-lived session.
 
         Args:
             key_id: The API key id.
@@ -163,10 +163,10 @@ class AuthClient:
 
 
 class TokenProvider(Protocol):
-    """Anything that can produce a bearer access token on demand."""
+    """Anything that can produce a bearer credential on demand."""
 
     async def get_token(self) -> str:
-        """Return a currently valid bearer access token."""
+        """Return a currently valid bearer credential."""
         ...
 
 
@@ -177,7 +177,7 @@ class StaticTokenProvider:
         """Store the token to hand out.
 
         Args:
-            token: The bearer access token to return from :meth:`get_token`.
+            token: The client token or API key to return from :meth:`get_token`.
         """
         self._token = token
 
@@ -224,7 +224,7 @@ class TokenManager:
         self._lock = asyncio.Lock()
 
     async def get_token(self) -> str:
-        """Return a valid access token, minting or refreshing when needed."""
+        """Return a valid bearer credential, renewing it when needed."""
         async with self._lock:
             if self._token is not None and self._clock() < self._refresh_at:
                 return self._token

{interhumanai-1.2.2 → interhumanai-1.3.0}/src/interhumanai/client.py

@@ -35,7 +35,7 @@ class InterhumanClient:
     Args:
         key_id: API key id (paired with ``key_secret``).
         key_secret: API key secret.
-        access_token: Pre-issued bearer token (JWT or client token).
+        access_token: A client token, or your API key, used as-is.
         scopes: Scopes requested when exchanging credentials. Defaults to
             upload + stream. Ignored when ``access_token`` is used.
         environment: Named environment to call. Defaults to ``production``.

{interhumanai-1.2.2 → interhumanai-1.3.0}/src/interhumanai/types.py

@@ -226,6 +226,20 @@ class UploadModel(str, enum.Enum):
     INTER_2_DEEP = "inter-2-deep"
 
 
+class UploadJobIncludeFlag(str, enum.Enum):
+    """Whole-file sections a ``POST /v2/upload/analyze`` job's result can carry.
+
+    The two :class:`IncludeFlag` Conversation Quality Index sections, plus
+    ``SIGNALS`` for the whole-file signal list
+    (:attr:`UploadJobResult.signals`). ``SIGNALS`` is a v2 upload option only;
+    :meth:`~interhumanai.UploadClient.analyze` and the stream do not take it.
+    """
+
+    CONVERSATION_QUALITY_OVERALL = "conversation_quality_overall"
+    CONVERSATION_QUALITY_TIMELINE = "conversation_quality_timeline"
+    SIGNALS = "signals"
+
+
 class UploadJobStatus(str, enum.Enum):
     """Lifecycle of a ``POST /v2/upload/analyze`` job.
 
@@ -285,13 +299,22 @@ class UploadJobConversationQuality(BaseModel):
 class UploadJobResult(BaseModel):
     """The result of a completed upload job: one entry per analyzed window.
 
+    ``signals`` is every window's signals as one list over the whole file, in
+    chronological order, merged by the same rules as
+    :meth:`~interhumanai.UploadClient.analyze` and with no ``modality``:
+    signals of the same type in adjacent windows become one span, which keeps
+    the highest probability and that signal's rationale. It is set only when the submit
+    passed :attr:`UploadJobIncludeFlag.SIGNALS`, and is then an empty list when
+    nothing was detected; ``windows`` are unchanged either way.
+
     ``conversation_quality`` is present only when the submit passed at least one
-    :class:`IncludeFlag`, and carries the sections those flags named.
+    Conversation Quality Index flag, and carries the sections those flags named.
     """
 
     duration_seconds: float
     window_seconds: float
     windows: list[UploadJobWindow] = Field(default_factory=list)
+    signals: list[UploadJobSignal] | None = None
     conversation_quality: UploadJobConversationQuality | None = None
 
 

{interhumanai-1.2.2 → interhumanai-1.3.0}/src/interhumanai/upload.py

@@ -13,7 +13,14 @@ from ._http import request_json
 from .auth import TokenProvider
 from .config import Environment, resolve_http_base_url
 from .errors import UploadJobTimeoutError
-from .types import AnalysisResult, GoalDimension, IncludeFlag, UploadJob, UploadModel
+from .types import (
+    AnalysisResult,
+    GoalDimension,
+    IncludeFlag,
+    UploadJob,
+    UploadJobIncludeFlag,
+    UploadModel,
+)
 
 DEFAULT_JOB_POLL_INTERVAL_SECONDS = 2.0
 """How often :meth:`UploadClient.wait_for_job` reads the job status by default."""
@@ -119,7 +126,7 @@ class UploadClient:
         *,
         model: UploadModel | str,
         wait_seconds: int = 0,
-        include: Sequence[IncludeFlag | str] | None = None,
+        include: Sequence[UploadJobIncludeFlag | IncludeFlag | str] | None = None,
         filename: str | None = None,
         content_type: str | None = None,
     ) -> UploadJob:
@@ -132,10 +139,11 @@ class UploadClient:
         it comes back ``queued`` or ``running`` and :meth:`wait_for_job` or
         :meth:`get_job` reads it later.
 
-        Pass ``include`` to have the completed job's result carry the
-        Conversation Quality Index over the whole file, in the sections the
-        flags name (:attr:`UploadJobResult.conversation_quality`). Without it
-        the result carries no such block.
+        Pass ``include`` to have the completed job's result carry whole-file
+        views: the Conversation Quality Index in the sections the CQI flags
+        name (:attr:`UploadJobResult.conversation_quality`), and the merged
+        signal list for ``SIGNALS`` (:attr:`UploadJobResult.signals`). Without
+        a flag the result carries no such section.
 
         For ``UploadModel.INTER_2`` the file is an mp4, mov, avi, mkv, webm or
         mpeg-ts video carrying both a video and an audio track (``ih5001``
@@ -151,10 +159,13 @@ class UploadClient:
             wait_seconds: How long the API may hold the request waiting for
                 the job to finish. ``0`` (the default) answers at once. The
                 deployment bounds it; a larger value raises ``ih4005``.
-            include: Conversation Quality Index sections the result should
-                carry: ``IncludeFlag.CONVERSATION_QUALITY_OVERALL`` and/or
-                ``IncludeFlag.CONVERSATION_QUALITY_TIMELINE``, the same flags
-                :meth:`analyze` takes. Omit it for no quality block.
+            include: Whole-file sections the result should carry, as
+                :class:`UploadJobIncludeFlag` values:
+                ``CONVERSATION_QUALITY_OVERALL`` and/or
+                ``CONVERSATION_QUALITY_TIMELINE`` (the same values
+                :meth:`analyze` takes, so :class:`IncludeFlag` members work
+                too) for the quality block, and ``SIGNALS`` for the signal
+                list. Omit a flag for no such section.
             filename: Filename reported to the API. Defaults to the path or
                 file object's name, else ``video``.
             content_type: MIME type of the file (e.g. ``video/mp4``).
@@ -172,7 +183,8 @@ class UploadClient:
             data["wait_seconds"] = str(wait_seconds)
         if include:
             data["include[]"] = [
-                flag.value if isinstance(flag, IncludeFlag) else flag for flag in include
+                flag.value if isinstance(flag, (IncludeFlag, UploadJobIncludeFlag)) else flag
+                for flag in include
             ]
         headers = {"Authorization": f"Bearer {token}"}
         url = self._base_url + "/v2/upload/analyze"