discourses.io Python SDK

Official Python SDK for discourses.io — the financial social media platform and financial language processing API

📄 Read the Whitepaper   ·   🔬 Methodology   ·   📖 Documentation   ·   🔑 Get API Key

Why discourses.io?

discourses.io is a financial social media platform and financial language processing API built for the modern market.

Traditional sentiment analysis treats language as static. But financial language evolves—"diamond hands" meant nothing in 2008, but signals strong conviction today. discourses.io solves this with era-calibrated lexicons built on academic and industrial quantitative research.

Installation

pip install discourses

Quick Start

from discourses import Discourses

client = Discourses(api_key="your-api-key")
result = client.analyze("Strong growth with excellent outlook ahead")

print(result.label)      # "very_bullish"
print(result.outlook)    # 0.99

API Reference

🔑 Initialize the Client

Every request requires authentication with your API key. Get yours at discourses.io/dashboard.

from discourses import Discourses

client = Discourses(api_key="your-api-key")

Endpoints

📊 Analyze — Single Text Sentiment

POST /analyze — Documentation

Analyze sentiment of any financial text. Returns classification, confidence, and detailed sentiment scores.

from discourses import Discourses

# Initialize client
client = Discourses(api_key="your-api-key")

# Analyze text
result = client.analyze("Strong growth with excellent outlook ahead")

# Access the results
print(f"Label:      {result.label}")
print(f"Confidence: {result.confidence:.2%}")
print(f"Outlook:    {result.outlook:.4f}")
print(f"Bullish:    {result.scores['bullish']:.4f}")
print(f"Bearish:    {result.scores['bearish']:.4f}")
print(f"Words:      {result.word_count}")

Expected Output:

Label:      very_bullish
Confidence: 80.05%
Outlook:    0.9257
Bullish:    0.4917
Bearish:    0.2981
Words:      6

🔄 Compare Eras — Cross-Era Analysis

POST /analyze/compare-eras — Documentation

Analyze how the same text is interpreted across different market eras. Essential for understanding semantic drift and backtesting strategies.

from discourses import Discourses

# Initialize client
client = Discourses(api_key="your-api-key")

# Compare sentiment across eras
result = client.compare_eras(
    text="This stock is going to the moon! Diamond hands!",
    eras=["primitive", "ramp", "meme", "present"]
)

# View per-era results
print("Era-by-Era Sentiment:")
print("-" * 50)
for era, data in result.results.items():
    label = data['classification']['label']
    outlook = data['scores']['outlook']
    print(f"  {era:12} {label:14} (outlook: {outlook:.4f})")

# Check semantic drift
print()
print(f"Drift Direction: {result.drift['direction']}")
print(f"Drift Magnitude: {result.drift['magnitude']:.4f}")
print(f"Peak Era:        {result.drift['peak_era']}")

Expected Output:

Era-by-Era Sentiment:
--------------------------------------------------
  primitive    bullish        (outlook: 0.6912)
  ramp         bullish        (outlook: 0.7845)
  meme         very_bullish   (outlook: 0.9933)
  present      very_bullish   (outlook: 0.9977)

Drift Direction: positive_shift
Drift Magnitude: 0.3065
Peak Era:        present

💡 Notice how "diamond hands" and "to the moon" have much stronger bullish signals in the meme and present eras compared to primitive!

⚡ Batch — High-Volume Processing

POST /analyze/batch — Documentation

Efficiently analyze multiple texts in a single request. Perfect for processing feeds, historical data, or real-time streams.

from discourses import Discourses

# Initialize client
client = Discourses(api_key="your-api-key")

# Texts to analyze (with custom IDs)
texts = [
    {"id": "post_1", "text": "Diamond hands! This is going to the moon"},
    {"id": "post_2", "text": "Bearish on this one, expecting a pullback"},
    {"id": "post_3", "text": "Strong growth with excellent outlook ahead"},
]

# Batch analyze with specific era
result = client.batch(texts=texts, era="meme")

# Process results
print("Batch Sentiment Analysis")
print("=" * 55)
for post_id, data in result.results.items():
    label = data['classification']['label']
    outlook = data['scores']['outlook']
    emoji = "🟢" if "bullish" in label else "🔴" if "bearish" in label else "⚪"
    print(f"{emoji} {post_id}: {label:14} (outlook: {outlook:.4f})")

print()
print(f"Processed: {result.meta['texts_processed']}")
print(f"Failed:    {result.meta['texts_failed']}")

Expected Output:

Batch Sentiment Analysis
=======================================================
🟢 post_1: bullish        (outlook: 0.6735)
🟢 post_2: very_bullish   (outlook: 0.9353)
🟢 post_3: very_bullish   (outlook: 0.9257)

Processed: 3
Failed:    0

Era Selection Guide

# Modern analysis (> 2023)
client.analyze(text, era="present")

# Meme-era analysis (2019-2023, WSB, crypto culture)
client.analyze(text, era="meme")

# Ramp era (2016-2019, fintech emergence)
client.analyze(text, era="ramp")

# Traditional financial language (< 2016)
client.analyze(text, era="primitive")

# Compare across all eras
client.compare_eras(text, eras=["primitive", "ramp", "meme", "present"])

Error Handling

The SDK provides typed exceptions for robust error handling:

from discourses import (
    Discourses,
    AuthenticationError,
    RateLimitError,
    ValidationError,
    DiscoursesError,
)

client = Discourses(api_key="your-api-key")

try:
    result = client.analyze("Market analysis text")
    
except AuthenticationError:
    # Invalid or expired API key
    print("Check your API key at https://discourses.io/dashboard")
    
except RateLimitError as e:
    # Too many requests
    print(f"Rate limited. Retry after {e.retry_after} seconds")
    
except ValidationError as e:
    # Invalid input (empty text, too long, etc.)
    print(f"Invalid input: {e.message}")
    
except DiscoursesError as e:
    # Catch-all for other API errors
    print(f"API error: {e}")

Links

License

MIT License — see LICENSE for details.

_{Built with ❤️ by discourses.io}