newsbot 0.1.2

Auto-posting news on X

xbot

News in, AI in the middle, tweets out. One Python package, zero code changes per bot -- everything that makes your bot yours (voice, sources, schedule, keys) lives in a single manifest.yaml.

from xbot import bot
bot.run()

That's the whole integration. bot reads manifest.yaml, pulls fresh headlines, asks an LLM to write something in your configured voice, and posts it to X. No boilerplate, no GitHub Actions required -- it's a library, not a framework. Drop it into a script, a cron job, a Flask endpoint, a Lambda, a Discord command -- wherever your own code lives.

Why it's built this way

Most "AI news bot" templates are a pile of scripts you fork and hack on per account. xbot flips that: the package is generic and never changes; everything account-specific is data in manifest.yaml. Point ten different manifests at ten different bots and you're running ten different accounts on identical code.

Install

pip install xbot

or from source:

git clone <this repo>
cd xbot
pip install -e .

Quick start

1. Copy manifest.example.yaml to manifest.yaml and fill in your X (Twitter) and Gemini API keys -- hardcode them for a quick local test, or use ${ENV_VAR_NAME} to pull from the environment.
2. Write a prompt or two under prompts/*.txt, each with a {{news_context}} placeholder that gets filled with fetched headlines.
3. Run it:

from xbot import bot

bot.run(dry_run=True)   # logs what it *would* post, doesn't call the X API

By default, bot is built from manifest.yaml in your current working directory the first time you touch it. Point it elsewhere:

export XBOT_MANIFEST=/path/to/other-manifest.yaml

Running several bots (or several accounts) in one process? Skip the singleton and build your own instances instead:

from xbot import XBot

morning_bot = XBot("bots/morning/manifest.yaml")
crypto_bot  = XBot("bots/crypto/manifest.yaml")

morning_bot.run(prompt_key="morning_flash")
crypto_bot.run()   # auto-picks a prompt based on time-of-day / random pool

There's also a CLI, useful for quick manual runs or debugging:

python -m xbot.cli --list-prompts
python -m xbot.cli --dry-run
python -m xbot.cli -p contrarian_view

What's in the manifest

• twitter / ai -- credentials for X and your LLM provider (Gemini out of the box, with a model-priority fallback list)
• news -- RSS sources to sample, how many to pull per run, and an image blacklist for filtering junk thumbnails
• prompts -- as many named "voices" as you want, each pointing at a .txt file. Give a prompt a time (UTC) and it becomes the one that fires around that time; leave it out and it's part of a random pool. Pick one explicitly in code with bot.run(prompt_key=...), no code changes needed to add a new voice -- just add an entry and a .txt file.
• run.dry_run -- log instead of post, handy for testing new prompts

Use cases

• Personal brand / niche accounts -- an always-on commentator voice for your niche (markets, sports, tech, whatever), running off a cron job or scheduler you already have.
• Multi-account operators -- one install, many manifests. Same code, different personalities, different accounts.
• Prototyping AI-driven social content -- swap prompts and models in a YAML file to A/B different voices without touching Python.
• Embedding in a bigger app -- since bot.run() is just a method call, wire it into whatever's already triggering your jobs: a web backend, a task queue, a Lambda on a schedule, an internal admin panel.

A note on hosting

xbot itself doesn't do scheduling, deployment, or secrets management -- that's intentional. It's the engine, not the hosting. Bring your own runner (cron, a task queue, a serverless function, whatever), or reach out if you'd rather have your bot hosted and run for you.

Project layout

xbot/                  # the generic package -- never changes per bot
  __init__.py           # `from xbot import bot` / `from xbot import XBot`
  core.py                # XBot -- ties everything together
  config.py              # manifest.yaml loading + validation
  ai_client.py            # Gemini wrapper with model fallback
  news_fetcher.py         # RSS/Atom fetch + image extraction
  twitter_client.py       # X API v1.1 media upload + v2 posting
  cli.py                   # `python -m xbot.cli`
  logger.py                # logging setup
  utils.py                  # shared helpers
manifest.example.yaml   # copy to manifest.yaml and fill in
prompts/                # your prompt .txt files go here

License

MIT (or whatever you choose to ship it as).