archeai-sdk 0.1.0__tar.gz

archeai_sdk-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+*.egg-info/
+dist/
+build/
+.env

archeai_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.5
+Name: archeai-sdk
+Version: 0.1.0
+Summary: Official Python SDK for the ArcheAI behavioral intelligence API — executive behavioral histories, deception-relevant signals, personality, and communication-style analytics from speech.
+Project-URL: Homepage, https://arche-ai.com
+Project-URL: Documentation, https://api.arche-ai.com/docs
+Author-email: ArcheAI <contact@arche-ai.com>
+License: MIT
+Keywords: alternative-data,behavioral-analytics,earnings-calls,nlp,quantitative-finance,voice-analysis
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Python: >=3.9
+Requires-Dist: requests>=2.28
+Provides-Extra: pandas
+Requires-Dist: pandas>=1.5; extra == 'pandas'
+Description-Content-Type: text/markdown
+
+# arche-ai
+
+Official Python SDK for the [ArcheAI](https://arche-ai.com) behavioral
+intelligence API — executive behavioral histories, deception-relevant
+signals, personality, and communication-style analytics from speech.
+
+```bash
+pip install arche-ai[pandas]
+```
+
+## Quant quickstart
+
+```python
+from arche_ai import ArcheClient
+
+c = ArcheClient(api_key="arche_sk_...")
+
+# Flagship: per-executive quarterly behavioral trajectories, from
+# ArcheAI's 1.8M-earnings-call research corpus (2005-present).
+# Point-in-time safe: each quarter's scores derive only from that
+# quarter's calls; history is append-only — safe for backtests.
+df = c.behavioral_history("AAPL", from_q="2018Q1")
+#   one row per (executive, quarter):
+#   7 communication-style z-scores + Big Five estimates
+
+# Example: flag executives breaching their own uncertainty baseline
+pivot = df.pivot_table(index="quarter", columns="executive",
+                       values="style_uncertain_certain")
+z = (pivot - pivot.expanding().mean()) / pivot.expanding().std()
+print(z.tail(4))  # who no longer sounds like themselves?
+```
+
+These are the same measures behind ArcheAI's published event-study
+results (out-of-sample lift over price, Loughran-McDonald sentiment,
+and SUE baselines at 1–5 day horizons).
+
+## Text analyses (async jobs)
+
+```python
+job = c.analyze_fraud_language(qa_transcript_text)  # >= 200 chars
+job = c.analyze_personality(text)
+job = c.analyze_style(text)
+
+result = c.wait(job)          # poll to completion
+print(result.result)
+```
+
+## Audio (bring your own recordings)
+
+```python
+audio_id = c.upload_audio("interview.wav")   # one call: 3-step flow
+job = c.analyze_deception_audio(audio_id)    # research signal
+job = c.analyze_voice_personality(audio_id)  # voice-only Big Five
+final = c.wait(job)
+```
+
+Uploaded audio is automatically deleted from storage after 7 days;
+delete sooner via the API or your account's My Data page.
+
+## Utilities
+
+```python
+c.models()    # available models + per-call credit costs
+c.account()   # remaining credits
+```
+
+## Important framing
+
+All scores are **research signals intended to inform professional
+judgment** — not investment advice, accusations, lie detection, or
+determinations of fact. Validation methodology, published nulls, and
+boundary conditions are documented at
+[api.arche-ai.com/docs](https://api.arche-ai.com/docs).
+
+## Roadmap
+
+- Speaker identification against ArcheAI's executive voiceprint
+  database (`speakers="auto"`)
+- Bulk/point-in-time history export for backtesting
+- Event-study starter kit (reproduce our published results on your
+  own universe)
+
+© ArcheAI. Contact: contact@arche-ai.com

archeai_sdk-0.1.0/README.md

@@ -0,0 +1,83 @@
+# arche-ai
+
+Official Python SDK for the [ArcheAI](https://arche-ai.com) behavioral
+intelligence API — executive behavioral histories, deception-relevant
+signals, personality, and communication-style analytics from speech.
+
+```bash
+pip install arche-ai[pandas]
+```
+
+## Quant quickstart
+
+```python
+from arche_ai import ArcheClient
+
+c = ArcheClient(api_key="arche_sk_...")
+
+# Flagship: per-executive quarterly behavioral trajectories, from
+# ArcheAI's 1.8M-earnings-call research corpus (2005-present).
+# Point-in-time safe: each quarter's scores derive only from that
+# quarter's calls; history is append-only — safe for backtests.
+df = c.behavioral_history("AAPL", from_q="2018Q1")
+#   one row per (executive, quarter):
+#   7 communication-style z-scores + Big Five estimates
+
+# Example: flag executives breaching their own uncertainty baseline
+pivot = df.pivot_table(index="quarter", columns="executive",
+                       values="style_uncertain_certain")
+z = (pivot - pivot.expanding().mean()) / pivot.expanding().std()
+print(z.tail(4))  # who no longer sounds like themselves?
+```
+
+These are the same measures behind ArcheAI's published event-study
+results (out-of-sample lift over price, Loughran-McDonald sentiment,
+and SUE baselines at 1–5 day horizons).
+
+## Text analyses (async jobs)
+
+```python
+job = c.analyze_fraud_language(qa_transcript_text)  # >= 200 chars
+job = c.analyze_personality(text)
+job = c.analyze_style(text)
+
+result = c.wait(job)          # poll to completion
+print(result.result)
+```
+
+## Audio (bring your own recordings)
+
+```python
+audio_id = c.upload_audio("interview.wav")   # one call: 3-step flow
+job = c.analyze_deception_audio(audio_id)    # research signal
+job = c.analyze_voice_personality(audio_id)  # voice-only Big Five
+final = c.wait(job)
+```
+
+Uploaded audio is automatically deleted from storage after 7 days;
+delete sooner via the API or your account's My Data page.
+
+## Utilities
+
+```python
+c.models()    # available models + per-call credit costs
+c.account()   # remaining credits
+```
+
+## Important framing
+
+All scores are **research signals intended to inform professional
+judgment** — not investment advice, accusations, lie detection, or
+determinations of fact. Validation methodology, published nulls, and
+boundary conditions are documented at
+[api.arche-ai.com/docs](https://api.arche-ai.com/docs).
+
+## Roadmap
+
+- Speaker identification against ArcheAI's executive voiceprint
+  database (`speakers="auto"`)
+- Bulk/point-in-time history export for backtesting
+- Event-study starter kit (reproduce our published results on your
+  own universe)
+
+© ArcheAI. Contact: contact@arche-ai.com

archeai_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "archeai-sdk"
+version = "0.1.0"
+description = "Official Python SDK for the ArcheAI behavioral intelligence API — executive behavioral histories, deception-relevant signals, personality, and communication-style analytics from speech."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "ArcheAI", email = "contact@arche-ai.com" }]
+keywords = [
+  "behavioral-analytics", "earnings-calls", "quantitative-finance",
+  "alternative-data", "nlp", "voice-analysis",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Financial and Insurance Industry",
+  "Intended Audience :: Science/Research",
+  "Programming Language :: Python :: 3",
+  "Topic :: Office/Business :: Financial :: Investment",
+]
+dependencies = [
+  "requests>=2.28",
+]
+
+[project.optional-dependencies]
+pandas = ["pandas>=1.5"]
+
+[project.urls]
+Homepage = "https://arche-ai.com"
+Documentation = "https://api.arche-ai.com/docs"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/arche_ai"]

archeai_sdk-0.1.0/src/arche_ai/__init__.py

@@ -0,0 +1,28 @@
+"""arche-ai — official Python SDK for the ArcheAI behavioral
+intelligence API.
+
+Quant-first design: the primary objects are point-in-time-safe
+behavioral score feeds keyed by ticker/executive/quarter, returned as
+pandas DataFrames when pandas is installed (plain dicts otherwise).
+
+Quickstart (quant):
+    from arche_ai import ArcheClient
+    c = ArcheClient(api_key="arche_sk_...")
+    df = c.behavioral_history("AAPL", from_q="2018Q1")
+    # -> one row per (executive, quarter): 7 style dims + Big Five
+
+Quickstart (text analytics):
+    job = c.analyze_fraud_language(text)      # research signal
+    job = c.analyze_personality(text)
+    job = c.analyze_style(text)
+    result = c.wait(job)                      # poll to completion
+
+All scores are research signals intended to inform professional
+judgment — not investment advice, accusations, or determinations of
+fact.
+"""
+
+from .client import ArcheClient, ArcheAPIError, Job
+
+__version__ = "0.1.0"
+__all__ = ["ArcheClient", "ArcheAPIError", "Job", "__version__"]

archeai_sdk-0.1.0/src/arche_ai/client.py

@@ -0,0 +1,206 @@
+"""ArcheAI API client — quant-first SDK core.
+
+Design notes:
+  - behavioral_history() is the flagship: point-in-time-safe quarterly
+    behavioral trajectories per executive. Long-format DataFrame out.
+  - Text analyses are async (job queue): analyze_*() returns a Job,
+    wait() polls it to completion.
+  - Audio upload wraps the 3-step signed-URL flow in one call.
+  - No pandas hard-dependency: DataFrame conversion degrades to
+    list-of-dicts when pandas is absent.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from typing import Optional
+
+import requests
+
+DEFAULT_BASE = "https://api.arche-ai.com"
+_UA = "arche-ai-python-sdk"
+
+
+class ArcheAPIError(Exception):
+    """API returned an error response."""
+
+    def __init__(self, status: int, code: str, message: str,
+                 meta: Optional[dict] = None):
+        self.status = status
+        self.code = code
+        self.message = message
+        self.meta = meta or {}
+        super().__init__(f"[{status} {code}] {message}")
+
+
+@dataclass
+class Job:
+    """Handle for an async analysis job."""
+    job_id: str
+    model: str
+    status: str = "queued"
+    result: Optional[dict] = None
+
+
+def _maybe_df(records: list, prefer_df: bool):
+    if not prefer_df:
+        return records
+    try:
+        import pandas as pd  # noqa: PLC0415
+        return pd.DataFrame(records)
+    except ImportError:
+        return records
+
+
+class ArcheClient:
+    """Client for the ArcheAI behavioral intelligence API.
+
+    Args:
+        api_key: your ArcheAI API key ("arche_sk_...").
+        base_url: override for staging gateways.
+        dataframes: return pandas DataFrames where natural (default
+            True; degrades to lists of dicts without pandas).
+    """
+
+    def __init__(self, api_key: str, base_url: str = DEFAULT_BASE,
+                 dataframes: bool = True, timeout: float = 60.0):
+        self._s = requests.Session()
+        self._s.headers.update({
+            "Authorization": f"Bearer {api_key}",
+            "User-Agent": _UA,
+        })
+        self._base = base_url.rstrip("/")
+        self._df = dataframes
+        self._timeout = timeout
+
+    def _req(self, method: str, path: str, **kw) -> dict:
+        r = self._s.request(method, self._base + path,
+                            timeout=self._timeout, **kw)
+        try:
+            body = r.json()
+        except ValueError:
+            body = {}
+        if r.status_code >= 400:
+            raise ArcheAPIError(
+                r.status_code,
+                str(body.get("error", "UNKNOWN")),
+                str(body.get("message", r.text[:200])),
+                body.get("meta"),
+            )
+        return body
+
+    # ── quant surface ────────────────────────────────────────────────
+    def behavioral_history(self, ticker: str,
+                           from_q: Optional[str] = None,
+                           to_q: Optional[str] = None):
+        """Per-executive quarterly behavioral trajectories for a
+        company (point-in-time safe; append-only history).
+
+        Long-format output: one row per (executive, quarter) with 7
+        communication-style z-scores + Big Five estimates.
+        Costs 5 credits per call.
+        """
+        params = {}
+        if from_q:
+            params["from"] = from_q
+        if to_q:
+            params["to"] = to_q
+        data = self._req(
+            "GET", f"/v1/companies/{ticker}/behavioral-history",
+            params=params)["data"]
+        records = []
+        for ex in data["executives"]:
+            for q in ex["quarters"]:
+                row = {
+                    "ticker": data["ticker"],
+                    "speaker_id": ex["speakerId"],
+                    "executive": ex["name"],
+                    "quarter": q["quarter"],
+                    "n_calls": q["nCalls"],
+                    "n_words": q["nWords"],
+                }
+                row.update({f"style_{k}": v
+                            for k, v in q["style"].items()})
+                row.update({f"big5_{k}": v
+                            for k, v in q["bigFive"].items()})
+                records.append(row)
+        return _maybe_df(records, self._df)
+
+    def account(self) -> dict:
+        """Account status incl. remaining credits."""
+        return self._req("GET", "/v1/account")["data"]
+
+    def models(self):
+        """List available models and per-call credit costs."""
+        data = self._req("GET", "/v1/models")["data"]
+        return _maybe_df(data, self._df)
+
+    # ── text analyses (async jobs) ───────────────────────────────────
+    def _analyze_text(self, line: str, text: str) -> Job:
+        data = self._req("POST", f"/v1/analyses/{line}",
+                         json={"text": text})["data"]
+        return Job(job_id=data["jobId"], model=line,
+                   status=data.get("status", "queued"))
+
+    def analyze_fraud_language(self, text: str) -> Job:
+        """Fraud-language screening for unscripted executive text
+        (research signal; >=200 chars required)."""
+        return self._analyze_text("fraud-language", text)
+
+    def analyze_personality(self, text: str) -> Job:
+        """Big Five personality estimate from unscripted text."""
+        return self._analyze_text("personality", text)
+
+    def analyze_style(self, text: str) -> Job:
+        """7-dimension communication style vs executive norms."""
+        return self._analyze_text("style", text)
+
+    # ── audio (signed-URL upload + async analyses) ───────────────────
+    def upload_audio(self, path: str,
+                     content_type: str = "audio/wav") -> str:
+        """Upload a local audio file (3-step signed-URL flow in one
+        call). Returns the audioId for analysis calls. Audio
+        auto-deletes from storage after 7 days."""
+        import os  # noqa: PLC0415
+        data = self._req("POST", "/v1/audio", json={
+            "filename": os.path.basename(path),
+            "contentType": content_type})["data"]
+        with open(path, "rb") as f:
+            up = requests.put(data["uploadUrl"], data=f,
+                              headers={"Content-Type": content_type},
+                              timeout=600)
+        up.raise_for_status()
+        self._req("POST", f"/v1/audio/{data['audioId']}/confirm")
+        return data["audioId"]
+
+    def analyze_deception_audio(self, audio_id: str) -> Job:
+        """Deception-relevant vocal indicators (research signal)."""
+        data = self._req("POST", "/v1/analyses/deception",
+                         json={"audioId": audio_id})["data"]
+        return Job(job_id=data["jobId"], model="deception")
+
+    def analyze_voice_personality(self, audio_id: str) -> Job:
+        """Voice-only Big Five (verification channel)."""
+        data = self._req("POST", "/v1/analyses/voice-personality",
+                         json={"audioId": audio_id})["data"]
+        return Job(job_id=data["jobId"], model="voice-personality")
+
+    # ── job polling ──────────────────────────────────────────────────
+    def job(self, job: "Job | str") -> Job:
+        """Fetch current job state."""
+        jid = job.job_id if isinstance(job, Job) else job
+        d = self._req("GET", f"/v1/jobs/{jid}")["data"]
+        return Job(job_id=jid, model=d.get("modelSlug", ""),
+                   status=d["status"], result=d.get("result"))
+
+    def wait(self, job: "Job | str", timeout: float = 300.0,
+             interval: float = 3.0) -> Job:
+        """Poll a job until completed/failed. Returns final Job."""
+        t0 = time.time()
+        while time.time() - t0 < timeout:
+            j = self.job(job)
+            if j.status in ("completed", "failed"):
+                return j
+            time.sleep(interval)
+        raise TimeoutError(f"job not finished in {timeout}s")