Skip to main content

hypeman-social

CI PyPI Python versions License: MPL 2.0 OpenSSF Scorecard Docs

A hype man's entire job is announcing you loudly to a crowd. That's what this library does: it's the shared core behind a family of daemons that shout about your content on Bluesky, Mastodon, Discord, Matrix, and Threads.

Daemon Shouts when
Boon-Tube-Daemon you post a YouTube video or Short
stream-daemon you go live on Twitch, YouTube, or Kick
Star-Daemon you star a GitHub repo
SolarStorm Scout the Sun does something worth telling the HF bands about

Why this exists

These daemons were three copies of the same code, drifting apart. Roughly 55-65% of the social-publishing code was identical line-for-line, and the LLM layer shared 352 identical lines across two files that had already diverged.

That duplication caused a real outage. An auto-reconnect fix for a local Ollama server was written for one daemon and never reached the other — and in the daemon that had it, the fix was unreachable anyway, because every call site gated on an enabled flag that the failure path set to False and nothing ever set back. Taking the AI server offline meant no AI until someone noticed and restarted the process.

A fix that lands in one repo should protect all of them. That's what this is for.

Install

Name note: the distribution is hypeman-social and the import is hypeman_social. Plain hypeman on PyPI is an unrelated project that ships its own top-level hypeman module, so this package deliberately avoids that name — installing both would otherwise break one of them silently.

pip install hypeman-social[all]

Every network and LLM backend is an optional extra, so install only what you use:

pip install hypeman-social[bluesky,mastodon,ollama]

Extras: bluesky, mastodon, ollama, gemini, aws, vault, doppler, all, dev.

Discord, Matrix, and Threads need no extra — they're plain HTTP.

Required secrets

A feature starts only with a real credential. An empty, unset or template value (YOUR_..., changeme, <token>, a webhook URL ending in YOUR_WEBHOOK_TOKEN) is treated as unset: the feature stays disabled, nothing is sent to the real service, and the log names the variable, never the value. The rule lives in one helper, hypeman_social.config.is_placeholder.

Secret Needed for Without it
DISCORD_WEBHOOK_URL Discord posting disabled
MATRIX_ACCESS_TOKEN or MATRIX_USERNAME + MATRIX_PASSWORD Matrix posting disabled
BLUESKY_APP_PASSWORD, MASTODON_ACCESS_TOKEN, THREADS_ACCESS_TOKEN those networks disabled
DISCORD_BOT_TOKEN, TWITCH_* tokens chat receiving unavailable
LLM_CLAUDE_API_KEY, LLM_OPENAI_API_KEY, LLM_GEMINI_API_KEY cloud LLMs provider disabled

Put them in the environment, Doppler, AWS Secrets Manager or Vault; the full rule and lookup order are in docs/CONFIGURATION.md.

Documentation

The same docs are browsable as a site at chiefgyk3d.github.io/hypeman.

Doc What's in it
Quickstart Build a complete announcement daemon in ~60 lines
Configuration reference Every env var, with defaults and worked examples
API reference The full public surface, module by module
Design notes Why it's shaped this way — the availability contract, opt-in failover, guardrail philosophy
Publishing PyPI Trusted Publishing setup and release procedure
Contributing Dev setup, the non-negotiable contracts, how to add platforms/providers
Changelog Release history

The availability contract

Never branch on .enabled. Always call is_available().

This is the entire lesson of the outage. is_available() is allowed to heal: if the provider is down but recoverable, it attempts a cooldown-guarded reconnect and reports the result. A gate that can only ever go from working to broken is not a health check, it's a latch.

from hypeman_social.llm import LLMManager, VIDEO_PROFILE

llm = LLMManager(profile=VIDEO_PROFILE)
llm.authenticate()

# Correct: this can recover a downed server.
if llm.is_available():
    message = llm.generate(prompt)

# Wrong: this is the bug. It can never come back.
# if llm.primary.enabled: ...

A failed authenticate() at startup is not fatal. Configuration is retained, and the daemon keeps trying in the background, so starting up while your AI box is offline costs you some template-fallback posts rather than a broken process.

Provider failover

Ollama and Gemini have complementary failure modes — your local box goes down for power cuts and GPU driver updates, Gemini goes down for rate limits and outages. They rarely go down together.

LLM_PROVIDER=ollama
LLM_FALLBACK_PROVIDER=gemini   # opt-in

Failover is opt-in by design. If you chose Ollama specifically so your data stays on your network, silently shipping prompts to Google would be a betrayal, not a feature. When the primary recovers, hypeman switches back automatically.

Validated generation in one call

message = llm.generate_validated(
    lambda strict: build_prompt(title, strict_mode=strict),
    title=title, username='chief', platform='bluesky',
    char_limit=300, expected_hashtags=3,
)

Generate, run the guardrails, and retry once with a stricter prompt when the first attempt has issues. If the retry still isn't clean, the original ships anyway — minor style problems beat silence — except for two hard vetoes: profanity (when the filter is on) and duplicates of recent posts. Every daemon used to reimplement this loop; now a fix to it reaches all of them.

Content profiles

The same guardrails apply everywhere, but the vocabulary differs. A stream announcement promising "VOD coming soon" is a hallucination; so is a video announcement claiming you're "live now". Rather than fork the guardrails, pass a profile:

from hypeman_social.llm.profiles import VIDEO_PROFILE, STREAM_PROFILE, ContentProfile

Define your own ContentProfile for anything else you're announcing.

Logging

Configurable level, optional rotating file output, and journald-aware formatting. Under systemd, timestamps are omitted automatically because journald already stamps every line.

LOG_LEVEL=INFO
LOG_FILE=/var/log/stream-daemon/daemon.log   # enables rotation
LOG_MAX_BYTES=10485760                       # 10 MB
LOG_BACKUP_COUNT=5
LOG_DEDUPE_SECONDS=300                       # collapse repeated poll lines

LOG_DEDUPE_SECONDS is the one to reach for if your logs are enormous. A daemon polling every two minutes writes ~720 identical "nothing happening" lines a day; this collapses them and reports the count. Warnings and errors are never suppressed.

from hypeman_social.observability import configure_logging
configure_logging()

Health

HEALTH_PORT=9101
  • GET /healthz — 200 alive, 503 something essential is broken
  • GET /status — full detail: every platform, the LLM, last poll, last post, uptime

A downed AI server reports as degraded, not unhealthy — the daemon is still doing its job with fallback messages, and a health check that cries wolf gets ignored.

Binds to 127.0.0.1 by default. The endpoint reports which platforms are configured and whether credentials work; expose it publicly only behind something that controls who can reach it.

Layout

hypeman_social.config          config + secrets (env, .env, AWS, Vault, Doppler)
hypeman_social.llm             Ollama + Gemini, guardrails, failover manager
hypeman_social.social          Bluesky, Mastodon, Discord, Matrix, Threads
hypeman_social.observability   logging with rotation, health endpoints

Nothing in here knows what you're announcing. That's the caller's business: daemons own their own prompts, polling, and state.

Adding a social network

Write the module, subclass SocialPlatform, add one line to REGISTRY in hypeman_social/social/__init__.py. Every daemon picks it up — that's exactly how Threads landed in 0.2.0. Full checklist — extras guard, config docs, fake-client tests — in CONTRIBUTING.md.

Development

pip install -e ".[all,aws,vault,doppler,dev]"
ruff check hypeman_social tests
pytest

CI is three short callers of the reusable workflows in git-your-ship-together (ci.yml, security.yml, release.yml), pinned by commit. It runs the same lint and tests across Python 3.9–3.13, a mypy type-check (the package ships py.typed), a bare-install smoke job (the package must work with zero extras), a coverage gate, actionlint and zizmor over the workflows, and on every pull request a build + twine check + wheel smoke test of the sdist and wheel. CodeQL, gitleaks, Semgrep and dependency review run on every pull request; OpenSSF Scorecard runs on main. docs.yml stays local because the shared workflows have no Pages deploy. Dependabot keeps the pins current.

Required status checks on main (branch protection):

  • ci / CI green
  • security / CI green
  • package / CI green

Each is the single gate job of its workflow: it needs every other job there, so a job added later cannot merge unchecked.

License

MPL-2.0


💝 Support This Project

If you find hypeman-social useful, consider supporting continued development. Everything is also collected at support.chiefgyk3d.com.

Recurring Support

Cryptocurrency Tips

Bitcoin Bitcoin
bc1qztdzcy2wyavj2tsuandu4p0tcklzttvdnzalla
Monero Monero
84Y34QubRwQYK2HNviezeH9r6aRcPvgWmKtDkN3EwiuVbp6sNLhm9ffRgs6BA9X1n9jY7wEN16ZEpiEngZbecXseUrW8SeQ
Ethereum Ethereum
0x554f18cfB684889c3A60219BDBE7b050C39335ED
Solana Solana
5T8h3HbyvHgLxwXgchRYbHSqRjZyAr8J7uwjLN9Fh8Jh

👤 Author & Socials

Made with ❤️ by ChiefGyk3D

Metadata

Release files for hypeman-social 0.4.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for hypeman-social 0.4.0
File Size Uploaded Provenance Actions
hypeman_social-0.4.0.tar.gz 198.8 kB With provenance Details for hypeman_social-0.4.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for hypeman-social 0.4.0
File Interpreter ABI Platform Actions
hypeman_social-0.4.0-py3-none-any.whl Python 3 none any Details for hypeman_social-0.4.0-py3-none-any.whl

Total release size: 331.7 kB

Release files / hypeman_social-0.4.0.tar.gz

Download URL hypeman_social-0.4.0.tar.gz
Size 198.8 kB
Tags Source
SHA-256 checksum
How to use checksums
35a807acc22f8543c8c6c2ccb76c88e956e92d212f1b03a0f70d2b0bcd9e64ae
BLAKE2b-256 checksum
How to use checksums
371cd7a7e667c1b5b6a75118c594ea49ba0f1ce51c1a33292770b254566a1a2b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 25, 2026.

Transparency log

Release files / hypeman_social-0.4.0-py3-none-any.whl

Download URL hypeman_social-0.4.0-py3-none-any.whl
Size 132.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
be1a1c884b2de215912e624c4d2382aa0ec3fd92402cec9f2faac98eda674987
BLAKE2b-256 checksum
How to use checksums
e69b9eebbb712addc446302f80f768b2d0eccdd7a421616d518941ac84b65a3d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 25, 2026.

Transparency log

Security for hypeman-social 0.4.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for hypeman_social-0.4.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 25, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page