Metadata-Version: 2.4
Name: rl-sales-augment
Version: 0.9.5
Summary: The decision layer frontier LLMs lack: an RL policy trained on outcomes decides WHEN to close; GPT/Gemini/Claude/Gemma write the words.
Author-email: Nandakishor M <nandakishor@convaiinnovations.com>
Maintainer-email: "Convai Innovations Pvt. Ltd." <nandakishor@convaiinnovations.com>
License: AGPL-3.0-or-later
Project-URL: Homepage, https://github.com/NandhaKishorM/rl-sales-augment
Project-URL: Repository, https://github.com/NandhaKishorM/rl-sales-augment
Keywords: reinforcement-learning,llm,sales,agent,augmentation,world-model
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.21
Requires-Dist: torch>=1.13
Provides-Extra: gemini
Requires-Dist: google-genai>=2.0.0; extra == "gemini"
Provides-Extra: openai
Requires-Dist: openai>=1.0; extra == "openai"
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.30; extra == "anthropic"
Provides-Extra: gemma
Requires-Dist: transformers>=5.0; extra == "gemma"
Requires-Dist: pillow; extra == "gemma"
Provides-Extra: mcp
Requires-Dist: mcp>=1.2; extra == "mcp"
Provides-Extra: api
Requires-Dist: fastapi>=0.110; extra == "api"
Requires-Dist: uvicorn; extra == "api"
Provides-Extra: docs
Requires-Dist: pypdf; extra == "docs"
Requires-Dist: python-docx; extra == "docs"
Requires-Dist: openpyxl; extra == "docs"
Provides-Extra: all
Requires-Dist: google-genai>=2.0.0; extra == "all"
Requires-Dist: openai>=1.0; extra == "all"
Requires-Dist: anthropic>=0.30; extra == "all"
Requires-Dist: transformers>=5.0; extra == "all"
Requires-Dist: pillow; extra == "all"
Requires-Dist: mcp>=1.2; extra == "all"
Requires-Dist: fastapi>=0.110; extra == "all"
Requires-Dist: uvicorn; extra == "all"
Requires-Dist: pypdf; extra == "all"
Requires-Dist: python-docx; extra == "all"
Requires-Dist: openpyxl; extra == "all"
Dynamic: license-file

# rl-sales-augment

A trained RL policy that picks the next sales move (rapport / pitch / objection / discount / close);
your LLM writes the words. The trained model downloads once on first use (sha-verified, cached):
CPU, no finetuning, works with any LLM.

```bash
pip install rl-sales-augment
```

## Quickstart (local Gemma, no API key)

The policy was trained alongside Gemma 4; running it fully local (E2B or E4B) is the first-class path:

```bash
pip install "rl-sales-augment[gemma]"
```

```python
import rl_sales_augment as rsa

gen = rsa.providers.gemma_e4b()      # google/gemma-4-E4B-it, auto-downloads, runs on CPU/MPS/CUDA
# gen = rsa.providers.gemma_e2b()    # google/gemma-4-E2B-it, the lighter 5B variant
bot = rsa.load_agent(gen, company_ctx="Acme sells AcmeBox, an $8k on-prem appliance.")

out = bot.reply("honestly it feels expensive vs AWS")
out["chosen_move"]   # 'RAPPORT'  <- the RL decision
out["belief"]        # {'interest': .5, 'trust': .5, 'budget_fit': .2, 'objection': .8, ...}
out["reply"]         # the LLM's words, executing that move
```

Prefer an API model? Same code, different one-liner:

```python
gen = rsa.providers.openai_chat(model="gpt-5.5")      # or gemini_api() / anthropic_chat()
```

`bot.reply()` is stateful: keep calling it, the agent remembers. For stateless use
(e.g. behind an API), pass the whole conversation in OpenAI message format:

```python
out = bot.chat([
    {"role": "user", "content": "what does it cost?"},
    {"role": "assistant", "content": "Depends on seats. How many do you need?"},
    {"role": "user", "content": "40 seats, but budget is tight"},
])
```

## Providers

```python
rsa.providers.gemma_e2b()                                     # [gemma]   local Gemma 4 E2B, no API key
rsa.providers.gemma_e4b()                                     # [gemma]   local Gemma 4 E4B, no API key
rsa.providers.openai_chat(model="gpt-5.5")                    # [openai]  OPENAI_API_KEY
rsa.providers.anthropic_chat(model="claude-sonnet-5")         # [anthropic] ANTHROPIC_API_KEY
rsa.providers.gemini_api()                                    # [gemini]  GEMINI_API_KEY
rsa.providers.gemini_vertex()                                 # [gemini]  gcloud ADC + GCP_PROJECT
rsa.providers.openai_chat(base_url="http://...")              # any OpenAI-compatible server
```

Or bring your own: any `gen(prompt) -> str` works.

On the Gemma E4B injection path the prompt is NEUTRAL (no persona, no style words): the human
voice comes from the RL latent itself, not prompt engineering.

**Multilingual:** the bot replies in the customer's language automatically (tested: Malayalam,
Hindi, Tamil, Japanese, Spanish, German; a built-in script detector keeps even small local models
on-language for Indic/CJK/Arabic/Cyrillic scripts). Romanized Indic is supported too: Manglish /
Hinglish / Tanglish ("ntha visesham, sugano?") is detected and mirrored on frontier models.

## API keys (.env)

Put credentials in a `.env` file next to where you run your script; providers load it
automatically (real environment variables take precedence). Never commit it.

```bash
# .env
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GEMINI_API_KEY=AIza...
GCP_PROJECT=my-gcp-project        # for gemini_vertex (gcloud ADC)
```

Explicit control: `rsa.load_env("/path/to/.env")`. Local Gemma needs no key at all.

## MCP server

```bash
pip install "rl-sales-augment[mcp]"
rl-sales-augment-mcp        # stdio
```

```json
{ "mcpServers": { "rl-sales-augment": { "command": "rl-sales-augment-mcp" } } }
```

Tools: `next_move` (buyer state → RL move), `perception_prompt`, `list_moves`, `list_segments`.

## REST API

```bash
pip install "rl-sales-augment[gemini,api]"
```

A complete FastAPI server (`POST /v1/chat`, OpenAI-format messages) ships in
[examples/fastapi_server.py](https://github.com/NandhaKishorM/rl-sales-augment/blob/main/examples/fastapi_server.py).

## Why not just call GPT-5.6 / Opus 4.8 / Gemini directly?

Because what kills LLM sales conversations isn't the words, it's the **timing**. Frontier models
are trained to be helpful and agreeable, so on a skeptical buyer they answer every objection
politely, forever, and never risk asking for the deal (measured: **0/4 closes on adversarial
buyers** while handling every question beautifully). A bigger model writes better sentences; it
doesn't fix this, because next-token training never rewards a deal that closes six turns later.

The bundled policy is different in kind, not degree:

- **Trained on outcomes, not text.** PPO over millions of simulated deals with delayed, stochastic
  rewards. It has *lost* deals to premature pitching, burned reputation on spam-closing, and learned
  that discounting converts SMBs but insults enterprise. An API model has read about selling; the
  policy has sold.
- **State-dependent timing.** Prompting "be assertive, always close" makes a bot uniformly pushy.
  The skill is *when*: the policy closes at high readiness and keeps building trust below it. Same
  LLM writing the words, right moment to ask. Result: 100% vs 19-31% close in a paired A/B, 3/4 vs
  0/4 on hard buyers (simulated; harness in the repo).
- **Consistent and auditable.** Sampled LLM strategy swings run-to-run; the policy is deterministic,
  and every turn logs `chosen_move` + `belief`, so you can see *why* it did what it did.
- **Complementary and tiny.** A ~1MB MLP on CPU. Keep GPT-5.6 / Opus 4.8 / Gemini for language,
  empathy, and knowledge; add the decision layer they don't have. Retrainable on your own funnel's
  economics (the commercial offering).

Details, transcripts, and a 67-second demo:
**[github.com/NandhaKishorM/rl-sales-augment](https://github.com/NandhaKishorM/rl-sales-augment)**

## License

AGPL-3.0-or-later. Training the policy on your own market is the commercial offering:
nandakishor@convaiinnovations.com (Convai Innovations Pvt. Ltd.).
