Metadata-Version: 2.4
Name: newsbot
Version: 0.1.1
Summary: Auto-posting news on X
Author: OmidAlek
Author-email: majid.alekasir@gmail.com
Keywords: python,X,Twitter,gemini,news,automation,Thread,prompt
Classifier: Development Status :: 1 - Planning
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: Unix
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows
Description-Content-Type: text/markdown
Requires-Dist: requests
Requires-Dist: requests-oauthlib
Requires-Dist: tweepy
Requires-Dist: google-genai
Requires-Dist: feedparser
Requires-Dist: beautifulsoup4
Requires-Dist: lxml
Requires-Dist: PyYAML
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: keywords
Dynamic: requires-dist
Dynamic: summary


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

```python
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

```bash
pip install xbot
```

or from source:

```bash
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:

```python
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:

```bash
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:

```python
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:

```bash
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).
