Metadata-Version: 2.4
Name: truenex-promoter
Version: 0.1.0a2
Summary: Autonomous AI marketing agent for open-source projects
Author-email: Marco Comunita <marco@truenex.ai>
License-Expression: Apache-2.0
Project-URL: Homepage, https://promoter.truenex.ai
Project-URL: Repository, https://github.com/marcomnit/truenex-promoter
Project-URL: Issues, https://github.com/marcomnit/truenex-promoter/issues
Project-URL: Changelog, https://github.com/marcomnit/truenex-promoter/blob/main/CHANGELOG.md
Keywords: marketing,open-source,github,promotion,agent
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Dynamic: license-file

# Truenex Promoter

Autonomous AI marketing agent for open-source projects. Monitors your repo, discovers promotion opportunities, generates content drafts, and **asks for your approval before taking action**.

> **Human-in-the-loop by design.** The agent proposes, you decide. No automated posts, no spam, no surprises.

[![PyPI](https://img.shields.io/pypi/v/truenex-promoter)](https://pypi.org/project/truenex-promoter/)
[![Python](https://img.shields.io/badge/python-3.12%2B-blue)](https://www.python.org/)
[![License](https://img.shields.io/badge/license-Apache%202.0-green)](LICENSE)

## Product Strategy: Open Core + Freemium UI

| Edition | Interface | What's included | Price |
|---|---|---|---|
| **OSS** | **CLI** (this repo) | Monitoring, queue, generators, LLM local/remote, hardware analyzer | **Free** |
| **Pro** | **Desktop UI** (Tauri) | System tray, dashboard, analytics, auto-executors | **$19/mo** |
| **Team** | **Desktop + Cloud** | Multi-repo, multi-user, sync | **$49/mo** |
| **Enterprise** | **SaaS Web** | Zero install, white-label, API, support | **Custom** |

The CLI is and will remain **open-source forever**. The UI is a closed-source paid add-on.

## Current Status

Alpha — dogfooding on [Truenex Memory](https://github.com/marcomnit/truenex-memory).

## What it does

1. **Monitors GitHub** — stars, issues, releases
2. **Detects milestones** — celebrates star milestones (10, 25, 50...)
3. **Discovers Awesome Lists** — finds relevant curated lists for your project
4. **Finds Stack Overflow questions** — unanswered questions matching your tags
5. **Generates drafts** — PR descriptions, social posts, dev.to articles, Product Hunt launches
6. **Queues for approval** — every action waits for your `approve` or `reject`

## Quick Start

```bash
# Install from PyPI
pipx install truenex-promoter
# or
pip install truenex-promoter

# Configure (optional)
export TRUENEX_PROMOTER_OWNER=your-org
export TRUENEX_PROMOTER_REPO=your-repo

# Check once
trnx-promoter
# or
python -m truenex_promoter

# Run continuously
trnx-promoter --loop

# View pending actions
trnx-promoter --queue

# Approve an action
trnx-promoter --approve <action-id>

# Reject an action
trnx-promoter --reject <action-id> --reason "not relevant"
```

## Configuration

All settings are via environment variables:

| Variable | Default | Description |
|---|---|---|
| `TRUENEX_PROMOTER_OWNER` | `marcomnit` | GitHub owner |
| `TRUENEX_PROMOTER_REPO` | `truenex-memory` | GitHub repo |
| `TRUENEX_PROMOTER_GITHUB_TOKEN` | — | GitHub personal access token |
| `TRUENEX_PROMOTER_INTERVAL` | `60` | Check interval in minutes |
| `TRUENEX_PROMOTER_LLM_PROVIDER` | `none` | `none`, `openai`, `deepseek`, `kimi`, `llamacpp` |
| `TRUENEX_PROMOTER_LLM_API_KEY` | — | API key for remote LLM |
| `TRUENEX_PROMOTER_LLM_MODEL` | — | Model name (e.g. `deepseek-chat`) |
| `TRUENEX_PROMOTER_LLM_MODEL_PATH` | — | Path to `.gguf` file for local LLM |
| `TRUENEX_PROMOTER_LLM_TEMPERATURE` | `0.7` | Sampling temperature (0.0–2.0) |
| `ENABLE_AWESOME_FINDER` | `true` | Discover Awesome Lists |
| `ENABLE_STACKOVERFLOW` | `true` | Find Stack Overflow questions |
| `ENABLE_DEVTO` | `true` | Generate dev.to drafts |
| `ENABLE_PRODUCTHUNT` | `true` | Generate Product Hunt drafts |

Configuration is validated on startup. Invalid values raise clear error messages.

## LLM Configuration

The promoter can use a local LLM (llama.cpp) or remote API.

### Local LLM (recommended: Nemotron 3 Nano 4B)

```bash
# Download Nemotron 4B Q4 (~3GB)
python -c "from huggingface_hub import hf_hub_download; hf_hub_download(repo_id='unsloth/NVIDIA-Nemotron-3-Nano-4B-GGUF', filename='NVIDIA-Nemotron-3-Nano-4B-Q4_K_M.gguf', local_dir='./models')"

# Configure
export TRUENEX_PROMOTER_LLM_PROVIDER=llamacpp
export TRUENEX_PROMOTER_LLM_MODEL_PATH="./models/NVIDIA-Nemotron-3-Nano-4B-Q4_K_M.gguf"
export TRUENEX_PROMOTER_LLM_N_GPU_LAYERS=-1

# Test
trnx-promoter --llm-check
```

### Remote API (OpenAI, DeepSeek, Kimi)

```bash
export TRUENEX_PROMOTER_LLM_PROVIDER=deepseek
export TRUENEX_PROMOTER_LLM_API_KEY=sk-...
export TRUENEX_PROMOTER_LLM_MODEL=deepseek-chat
trnx-promoter --llm-check
```

## Example Output

```
[2026-05-14 08:38:46 UTC] EVENT: NEW_RELEASE
Title: New release: v0.1.0-alpha.1
URL: https://github.com/marcomnit/truenex-memory/releases/tag/v0.1.0-alpha.1

[2026-05-14 08:38:46 UTC] ACTION PROPOSED (ID: 6696a400)
Title: Announce release v0.1.0-alpha.1
Approve:  trnx-promoter --approve 6696a400
Reject:   trnx-promoter --reject 6696a400

[2026-05-14 08:38:49 UTC] ACTION PROPOSED (ID: f15b266a)
Title: Propose addition to awesome-mcp-servers
Target: https://github.com/punkpeye/awesome-mcp-servers
```

## Architecture

```
trnx-promoter check
    -> github_monitor.check()      # fetch repo state
    -> content_generator           # draft posts/PRs/articles
    -> awesome_finder              # discover awesome lists
    -> stackoverflow_finder        # find relevant questions
    -> action_queue.add()          # queue for approval (SQLite)
    -> notifier.action_proposed()  # notify user

User: trnx-promoter --approve ID
    -> action_queue.approve()      # mark approved
    -> executor.execute()          # generate file + open browser
```

## Security

- **Token sanitization** — API keys and tokens are redacted from logs and error messages
- **Path traversal protection** — executor filenames are sanitized and bound-checked
- **Action type whitelist** — only known action types can be queued
- **Rate limiting** — GitHub API calls include retry with exponential backoff
- **SQLite persistence** — atomic operations prevent race conditions in the action queue

## Development

```bash
# Clone
git clone https://github.com/marcomnit/truenex-promoter.git
cd truenex-promoter

# Install editable
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Build
python -m build
```

## License

Apache 2.0
