NostrSocial

Install

Minimal dependencies: bech32 only. No heavyweight crypto libraries required.

Links

Quickstart

Create an enclave, add a contact, get tier-based behavior rules.

from nostrsocial import SocialEnclave, Tier

# Create an enclave and back up the device secret immediately
enclave = SocialEnclave.create()
secret = enclave.export_secret()  # Store this securely

# Add a contact and get tier-based behavior
enclave.add("alice@example.com", "email", Tier.CLOSE, display_name="Alice")
rules = enclave.get_behavior("alice@example.com", "email")
# rules.warmth=0.8, rules.token_budget=1500, rules.can_interrupt=True

Core Capabilities

1. Manage Contacts

Add contacts to friends, block, or gray lists with capacity enforcement.

from nostrsocial import SocialEnclave, Tier

enclave = SocialEnclave.create()
enclave.add("alice@example.com", "email", Tier.CLOSE, display_name="Alice")
enclave.block("spam@bad.com", "email")
enclave.gray("meh@example.com", "email")

2. Query Behavioral Rules

Get tier-based behavioral parameters for any contact. Unknown contacts get neutral behavior.

rules = enclave.get_behavior("alice@example.com", "email")
# rules.token_budget, rules.warmth, rules.can_interrupt, etc.

# Unknown contacts get neutral behavior
rules = enclave.get_behavior("stranger@example.com", "email")
# warmth=0.5, token_budget=500

3. Evaluate Conversations

Combine WHO someone is with WHAT is happening to determine HOW to respond. Pass ConversationSignals and get back an Evaluation with adjusted warmth, token budget, approach guidance, and a recommended action.

from nostrsocial import ConversationSignals

signals = ConversationSignals(
    sentiment="vulnerable",
    vulnerability=0.7,
    reciprocity=0.8,
    engagement=0.9,
    topic_depth=0.6,
)
result = enclave.evaluate("alice@example.com", "email", signals)
# result.action = Action.HOLD
# result.approach = "full presence"
# result.adjusted_warmth = 0.96
# result.adjusted_token_budget = 1950

4. Screen Content (Guardrails)

Screen conversation text for banned words, topics, and patterns. Returns a ScreenResult with severity, category, and recommended action.

result = enclave.screen("some incoming message text")
if result.flagged:
    print(result.action)     # "block", "exit", "warn", or "demote"
    print(result.severity)   # 0.0-1.0
    print(result.category)   # "slurs", "manipulation", etc.
    print(result.matched)    # "[slurs]" (never raw input)

# Screen display names for known bad-actor patterns
result = enclave.screen_entity("crypto_support_official")

5. Network Shape

Analyze the social graph and get a human-readable profile.

shape = enclave.network_shape()
# shape.profile_type = "balanced", "fortress", "deep-connector", etc.
# shape.narrative = "12 friends (2 intimate, 4 close, ...)
# shape.tier_counts, shape.verified_count, shape.avg_interaction_days

6. Auto-Maintenance

Run drift detection, gray decay, and at-risk reporting in a single call. Use dry_run=True to preview changes without committing them.

# Preview what would happen
preview = enclave.maintain(dry_run=True)
print(preview["summary"])

# Execute maintenance for real
result = enclave.maintain()
# result["drifted"], result["decayed"], result["at_risk"], result["summary"]

7. Cross-Channel Recognition

Recognize the same person across different channels. This is resonance, not surveillance, it only checks contacts you already have a relationship with.

# Check if a new contact might be someone you already know
matches = enclave.recognize(
    "alicedev", "twitter",
    display_name="Alice",
)
for match in matches:
    print(f"{match.confidence}: {match.reason}")

# Explicitly link two identities (never auto-linked)
result = enclave.link(
    "alice@example.com", "email",
    "alicedev", "twitter",
)

8. Identity Verification

Track identity state from proxy to claimed to verified.

# See who needs verification
for contact in enclave.get_upgradeable():
    print(f"{contact.display_name}: {contact.upgrade_hint}")

# Create a challenge for a claimed npub
challenge = enclave.create_challenge("npub1alice...")

9. Persistence

Save and load the social graph.

from nostrsocial import FileStorage

storage = FileStorage("~/.agent/social.json")
enclave = SocialEnclave.create(storage)
enclave.add("alice@example.com", "email", Tier.CLOSE)
enclave.save()

# Later
enclave = SocialEnclave.load(storage)

Trust Tiers

Friends list total: 150 (Dunbar's number). Unknown contacts get neutral behavior (warmth 0.5, budget 500).

Response Format

Contact

Returned by add(), promote(), demote().

BehaviorRules

Returned by get_behavior().

Evaluation

Returned by evaluate().

ScreenResult

Returned by screen().

NetworkShape

Returned by network_shape().

When to Use Each Module

Security

• The device secret is the root of all proxy npub derivation. Call export_secret() after create() and store it securely. If you lose it, all proxy npubs become unrecoverable.
• Never hardcode an nsec in your code. If your agent has a Nostr identity, load it from an environment variable or encrypted file. The nostrkey package provides Identity.load() for this.
• ScreenResult.matched never exposes raw input. It returns category tags like [slurs] to prevent PII leakage in logs or downstream systems.
• Guardrails use bundled defaults from data/*.json (banned words, topics, entities). Operators can override or extend via extra_words, extra_topics, and extra_entities parameters.
• Proxy npubs are deterministic (HMAC-SHA256), same identifier always maps to same npub.
• Challenge verification requires relay interaction, stub only in 0.1.0.

Configuration

Capacity Constants

All capacity constants are defined in types.py and can be overridden via SocialEnclave.create(tier_capacity=..., list_capacity=...).

Identity States

Drift Thresholds

NIP Integration

NostrSocial works with Nostr identity but does not require relay connectivity for core operations. Proxy npubs are derived locally via HMAC-SHA256.

Ecosystem

NostrSocial is Pillar 4 of the NSE platform, the relationships layer. It works standalone or alongside the other OpenClaw skills.