Metadata-Version: 2.5
Name: archeai-sdk
Version: 0.3.1
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://github.com/ArcheAI/arche-ai-sdk/tree/main/docs
Project-URL: API Reference, https://api.arche-ai.com/docs
Project-URL: Source, https://github.com/ArcheAI/arche-ai-sdk
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

# archeai-sdk

Official Python SDK for the [ArcheAI](https://arche-ai.com) behavioral
intelligence API — executive behavioral histories, multi-speaker session
analysis, deception-relevant signals, personality, and communication-style
analytics from speech.

```bash
pip install "archeai-sdk[pandas]"
```

## Documentation

| | |
|---|---|
| [Getting started](docs/getting-started.md) | install, auth, the three request shapes, which method to use, credits, trials, data handling |
| [Quant: behavioral history](docs/quant.md) | `behavioral_history()` — every parameter and every output column |
| [Text analyses](docs/text.md) | fraud-language, personality, style, batch — parameters + result fields |
| [Audio (single speaker)](docs/audio.md) | upload, deception, voice personality, pair, convergence, one-call flow |
| [Sessions (multi-speaker)](docs/sessions.md) | `analyze_session()` — diarization + per-speaker scores + time series, PHI mode |
| [Jobs, account, models](docs/jobs.md) | polling, credits, model catalog |
| [Interpreting scores](docs/interpreting-scores.md) | what z-scores, 1–7 traits, and 0–1 signals mean — and their limits |
| [Errors](docs/errors.md) | every error code and what to do |

Every public method also carries the same documentation in its docstring
(`help(ArcheClient.analyze_session)`), and the REST API's own reference is
at [api.arche-ai.com/docs](https://api.arche-ai.com/docs).

## 30-second tour

```python
from arche_ai import ArcheClient
c = ArcheClient(api_key="arche_sk_...")

# Quant: one row per (executive, quarter), point-in-time safe
df = c.behavioral_history("AAPL", from_q="2018Q1")

# Text: async job -> wait -> result dict
style = c.wait(c.analyze_style(exec_answers)).result

# Single-speaker clip: upload -> analyze -> wait -> (delete), one call
out = c.analyze_file("clip.wav", lines=("deception", "voice-personality"),
                     delete_after=True)

# Multi-speaker recording: diarize + transcribe + per-speaker scores
sess = c.analyze_session("interview.wav", phi=True)   # HIPAA-mode example
sess.speaker_frame()      # per-speaker Big Five + style
sess.segment_frame()      # per-speaker behavioral time series
```

## 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
