Metadata-Version: 2.5
Name: agent-prose
Version: 1.0.0
Summary: Deterministic Anti-RLHF Stylometric Gate for Autonomous Agents by Nitivra
Project-URL: Homepage, https://github.com/geheharidas/agent-prose
Project-URL: Repository, https://github.com/geheharidas/agent-prose.git
Author-email: Nitivra <hello@nitivra.com>
License-Expression: MIT
License-File: LICENSE
Keywords: anti-rlhf,autonomous-agents,burstiness,cadence,linter,llm,pre-commit,stylometrics,writing-quality
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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 :: Software Development :: Quality Assurance
Classifier: Topic :: Text Processing :: Linguistic
Requires-Python: >=3.9
Description-Content-Type: text/markdown

<!-- writing-quality: off -->
# agent-prose

> Deterministic Anti-RLHF Stylometric Gate for Autonomous Agents.  
> Created and maintained by **Nitivra**.

[![CI](https://github.com/geheharidas/agent-prose/actions/workflows/test.yml/badge.svg)](https://github.com/geheharidas/agent-prose/actions)
[![PyPI](https://img.shields.io/pypi/v/agent-prose.svg)](https://pypi.org/project/agent-prose/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Python: 3.9+](https://img.shields.io/badge/python-3.9%2B-blue)](https://www.python.org/downloads/)

Traditional linters check human grammar. They search for misspellings and punctuation errors that modern large language models rarely make.

They completely miss the real reason human readers identify AI-generated text in seconds: **cadence symmetry, evasive verbs and synthetic balance**.

Foundation models trained through Reinforcement Learning from Human Feedback (RLHF) develop predictable stylometric tells:
- **Monotone Sentence Cadence**: Running four or five consecutive sentences of nearly identical word length (18 to 24 words).
- **Copula Avoidance**: Refusing to write direct statements like "X is Y", substituting evasive constructions such as "X serves as Y", "stands as" or "represents a".
- **Prestige Filler Stems**: Overusing academic scaffolding words like "crucial", "nuance", "bedrock", "linchpin" and "cornerstone".
- **Synthetic Balance**: Forcing thoughts into artificial balance structures like "not only X, but also Y".
- **Tacked-on Participial Tails**: Appending weak participial clauses to sentence endings (", ensuring that...", ", enabling...").

`agent-prose` is a zero-dependency Python gate and pre-commit hook that detects these structural distortions deterministically in under two milliseconds.

---

## Why It Matters

When software engineering teams deploy autonomous agents to generate documentation, pull request summaries, technical specifications and customer communications, text quality directly reflects company credibility.

If your documentation reads like generic corporate boilerplate, readers tune out immediately.

`agent-prose` replaces subjective editorial debates with an automated, reproducible quality gate in your continuous integration pipeline.

---

## What It Evaluates

1. **Sliding-Window Burstiness Analysis**: Measures syntactic variance across five-sentence blocks. Requires sentence length standard deviation to reach at least 6.0, penalising monotone runs.
2. **Direct Copula Enforcement**: Flags evasive linking verbs and restores direct declarative active voice.
3. **Pluggable Dialect Packs**:
   - **Australian English (`en-AU`)**: Australian Government Style Manual and Macquarie standard. Strict `-ise` spellings, British orthography (`colour`, `centre`) and Oxford comma banned.
   - **American English (`en-US`)**: Chicago Manual of Style and AP standard. `-ize` spellings and serial comma permitted.
   - **British English (`en-GB`)**: Oxford UK standard.
4. **Two-Tier Severity Architecture**:
   - **Blocking Defects (Exit Code 1)**: Fatal issues including non-ASCII smart quotes, invalid dialect spellings, contractions and raw flow arrows (`->`) in narrative prose.
   - **Advisory Warnings**: Cadence anomalies, prestige stems and synthetic balance.
   - **Promotion Quota (Exit Code 2)**: Accumulating four or more advisory warnings promotes the scan to a blocking process exit.
5. **Agent Swarm Remediation Bounds**: Includes recommended two-pass repair loop specifications to prevent autonomous agents from getting trapped in circular editing loops.

---

## Installation

Install from PyPI:

```bash
pip install agent-prose
```

Or run instantly without installation using `uv`:

```bash
uv tool run agent-prose path/to/document.md
```

Or install directly from GitHub:

```bash
pip install git+https://github.com/geheharidas/agent-prose.git
```

---

## Quickstart

Scan a single document:

```bash
agent-prose README.md
```

Scan an entire directory recursively:

```bash
agent-prose docs/
```

Specify a dialect profile:

```bash
# Australian English (strict -ise, colour, Oxford comma banned):
agent-prose --locale en-AU docs/

# American English (-ize, color, Oxford comma permitted):
agent-prose --locale en-US docs/
```

Run in strict mode (all warnings become blocking errors):

```bash
agent-prose --strict docs/
```

Emit machine-readable JSON results for automated CI tooling:

```bash
agent-prose --json docs/
```

---

## Pre-Commit Hook Integration

Add `agent-prose` to your repository `.pre-commit-config.yaml` to gate pull requests automatically:

```yaml
repos:
  - repo: https://github.com/geheharidas/agent-prose
    rev: v1.0.0
    hooks:
      - id: agent-prose
        args: ["--locale", "en-AU"]
```

---

## Dialect Resolution Cascade

`agent-prose` resolves your active regional profile through an automated 5-stage cascade:
1. Command-line argument: `--locale <code|path>`
2. Project configuration: `.proserc.json` or `[tool.agent-prose]` in `pyproject.toml`
3. Environment variable: `AGENT_PROSE_LOCALE`
4. Host operating system locale detection: `locale.getlocale()`
5. Fallback baseline: `en-US`

---

## Multi-Agent Swarm Priming Adapters

Preventing errors before generation is faster than remediation. `agent-prose` provides calibration blocks tailored to specific model family failure modes:

- **Anthropic Claude**: Suppresses prestige academic scaffolding (`crucial`, `nuance`, `bedrock`).
- **Google Gemini**: Enforces burstiness variation and eliminates trailing participial clauses.
- **xAI Grok**: Suppresses informal conversational swagger and prose arrows (`->`).
- **Meta Muse / Llama**: Enforces strict dialect orthography and bans contractions.
- **Microsoft Copilot**: Eliminates corporate marketing fluff (`empower`, `seamless`) and conversational customer-service patter.

View adapter templates in `src/agent_prose/adapters/` or generate them dynamically:

```python
from agent_prose.adapters import get_adapter_prompt

claude_prompt = get_adapter_prompt("claude", profile=None)
print(claude_prompt)
```

---

## Zero Dependencies, Sub-2ms Latency

`agent-prose` relies exclusively on Python standard library modules (`re`, `pathlib`, `collections`, `statistics`, `json`, `locale`).

It introduces zero third-party supply chain risks, installs in seconds and scans complete technical specifications in under two milliseconds.

---

## License

MIT License. Copyright (c) 2026 **Nitivra**.
