paygent 0.1.0__tar.gz

paygent-0.1.0/.gitignore

@@ -0,0 +1,42 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.egg-info/
+*.egg
+dist/
+build/
+
+# Virtual environments
+venv/
+.venv/
+
+# Environment variables
+.env
+.env.local
+.env.test
+
+# IDE
+.vscode/
+.idea/
+*.sw?
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# SQLite
+*.sqlite
+*.db
+
+# Logs
+*.log

paygent-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,427 @@
+# Contributing to Paygent
+
+This doc is for people working on the Paygent SDK itself — setup, architecture,
+running the full stack, tests, and publishing releases.  For end-user docs see
+the [README](./README.md).
+
+---
+
+## Table of contents
+
+- [Repository layout](#repository-layout)
+- [Dev environment setup](#dev-environment-setup)
+- [Running the tests](#running-the-tests)
+- [Running the backend locally](#running-the-backend-locally)
+- [Architecture](#architecture)
+  - [Call path](#call-path)
+  - [Two-phase reservation (concurrency safety)](#two-phase-reservation-concurrency-safety)
+  - [Event queue and background sync](#event-queue-and-background-sync)
+- [Local storage (SQLite)](#local-storage-sqlite)
+  - [Schema](#schema)
+  - [Debugging with SQLite](#debugging-with-sqlite)
+- [Coding standards](#coding-standards)
+- [Known gotchas](#known-gotchas)
+- [Release process](#release-process)
+
+---
+
+## Repository layout
+
+Paygent lives in one monorepo with three workspaces:
+
+```
+code/
+├── sdk/                     # The Python SDK (published to PyPI)
+│   ├── src/paygent/         # SDK source
+│   ├── tests/               # SDK unit tests
+│   └── pyproject.toml
+├── backend/                 # FastAPI backend (not published)
+│   ├── src/paygent_api/
+│   ├── tests/
+│   ├── alembic/             # DB migrations
+│   └── docker-compose.yml
+└── tests/e2e/               # End-to-end tests that exercise SDK ↔ backend
+```
+
+## Dev environment setup
+
+### Prerequisites
+
+- Python 3.10+
+- Docker (for PostgreSQL when working on the backend or running e2e tests)
+- `OPENAI_API_KEY` and `ANTHROPIC_API_KEY` if you want to run real-LLM e2e tests
+
+### Install
+
+```bash
+git clone https://github.com/paygent/paygent.git
+cd paygent
+
+# SDK dev install
+cd sdk
+python3 -m venv venv
+venv/bin/pip install -e '.[dev]'
+
+# Backend dev install (separate venv; the two codebases are independent)
+cd ../backend
+python3 -m venv venv
+venv/bin/pip install -e '.[dev]'
+```
+
+### Optional framework extras
+
+Install these only if you need to run the LangChain/LangGraph/CrewAI test
+paths locally:
+
+```bash
+sdk/venv/bin/pip install langchain-openai langchain-anthropic langgraph crewai
+```
+
+## Running the tests
+
+The project has three test suites.  Each has its own runner.
+
+### SDK unit tests (no backend, no real LLM)
+
+```bash
+cd sdk
+venv/bin/python -m pytest tests/ -q
+```
+
+Expect ~500 tests in under 10 seconds.
+
+### Backend unit tests (no SDK, no real LLM, needs PostgreSQL)
+
+```bash
+cd backend
+docker compose up -d   # start PostgreSQL
+venv/bin/python -m pytest tests/ -q
+```
+
+### End-to-end tests (full stack — backend + real LLM calls)
+
+The e2e suite has its own runner that spins up a dedicated test backend on
+port 8001 against the `paygent_test` database:
+
+```bash
+./tests/e2e/run_e2e.sh                              # everything
+./tests/e2e/run_e2e.sh tests/e2e/test_phase3_langchain.py
+./tests/e2e/run_e2e.sh -k "hard_gate"
+```
+
+See [`tests/README.md`](../tests/README.md) for the full e2e reference —
+phases, fixtures, markers, env vars.
+
+## Running the backend locally
+
+If you're working on the SDK and want to point it at a local backend:
+
+```bash
+# Start PostgreSQL
+cd backend
+docker compose up -d
+
+# Run migrations
+PYTHONPATH=src venv/bin/python -m alembic upgrade head
+
+# Start the server on port 8000 (default)
+PYTHONPATH=src venv/bin/uvicorn paygent_api.main:app --reload
+```
+
+Health check: `curl http://localhost:8000/api/v1/health`
+
+PgAdmin is available at [http://localhost:8080](http://localhost:8080) via
+docker-compose.
+
+## Architecture
+
+### Call path
+
+Every metered LLM call (via auto-instrumentation or `pg.wrap()`) goes
+through the same four-step pipeline:
+
+```
+User sends prompt
+    |
+Paygent SDK intercepts LLM call
+    |
+Guard check + reservation (under per-user lock, microseconds)
+    |           |
+    |           +--> hard_gate?  raise PaygentLimitExceeded
+    |           +--> soft_gate?  fire callback, continue
+    |           +--> ok?         reserve estimated cost
+    |
+Original LLM call executes (lock released, concurrent calls interleave)
+    |
+Metering: extract tokens, finalize reservation (under lock, microseconds)
+    |
+Event pushed to background queue (non-blocking)
+    |
+Response returned IMMEDIATELY
+
+[Background thread] Events batched and synced to the Paygent backend
+```
+
+The per-user lock is held only for the two short windows around the LLM
+call — never across the network I/O.  Concurrent calls for the same user
+run their HTTP round-trips in parallel.
+
+### Two-phase reservation (concurrency safety)
+
+Without a reservation, two concurrent calls at the boundary of a cap can
+both pass the guard (both see the same stale `period_cost`) and both
+execute — doubling the overrun.
+
+The reservation pattern fixes this:
+
+1. **Reserve** — after the guard passes, tentatively add the estimated
+   cost to a separate `reserved_cost` field.  Subsequent concurrent guard
+   checks see `period_cost + reserved_cost` and can block.
+2. **Execute** — lock released, LLM call runs.
+3. **Finalize** — atomic swap under the lock: subtract the reservation,
+   add the actual cost from the response.  Net recorded spend = actual.
+
+The `reservation_safety_factor` (default 1.2) absorbs estimation drift.
+A 20% multiplier on the reservation hold means 20% of bonus headroom is
+held during the await — prevents small token-counting errors from
+overshooting.  Actual spend is never inflated.
+
+Errors roll back the reservation:
+- LLM call raises → `release_reservation` → re-raise
+- Token extraction fails → `release_reservation` → swallow (fail-open)
+- Event creation fails → `release_reservation` → swallow
+
+### Event queue and background sync
+
+A single `threading.Thread` (daemon) runs the flush loop:
+
+- Every `flush_interval` seconds (default 5s), drain the in-memory queue
+  and push to the backend in batches.
+- Every `sync_pending_interval` (default 30s), retry previously-unsynced
+  events stored in SQLite.
+- Every `refresh_interval` (default 60s), fetch fresh user state from
+  the backend for every cached user.
+
+If the backend is unreachable, events stay in SQLite marked `synced=0`.
+They retry on the next `sync_pending` cycle when the backend returns.
+
+## Local storage (SQLite)
+
+Paygent maintains a local SQLite database at `~/.paygent/local.db` by
+default (configurable via `db_path`).  This database serves two purposes:
+
+1. **Offline fallback** — events are written locally before the backend
+   sync attempt.  If the backend is down, they queue here and sync on
+   reconnect.
+2. **Local-only mode** — when no API key is provided, this is the sole
+   storage for usage data.
+
+### Schema
+
+```sql
+-- Every metered event
+CREATE TABLE usage_events (
+    id TEXT PRIMARY KEY,              -- UUID (idempotency key)
+    user_id TEXT NOT NULL,
+    session_id TEXT,                  -- Optional
+    timestamp TEXT NOT NULL,          -- ISO 8601
+    model TEXT,                       -- e.g. "gpt-4o"
+    input_tokens INTEGER DEFAULT 0,
+    output_tokens INTEGER DEFAULT 0,
+    total_tokens INTEGER DEFAULT 0,
+    tool_calls TEXT DEFAULT '[]',     -- JSON array
+    cost_tokens REAL DEFAULT 0,
+    cost_tools REAL DEFAULT 0,
+    cost_total REAL DEFAULT 0,
+    metadata TEXT DEFAULT '{}',       -- JSON blob
+    synced INTEGER DEFAULT 0,         -- 0 = pending, 1 = synced
+    created_at TEXT DEFAULT (datetime('now'))
+);
+
+CREATE INDEX idx_events_user ON usage_events(user_id, timestamp);
+CREATE INDEX idx_events_synced ON usage_events(synced);
+
+-- Per-user cached state for offline recovery
+CREATE TABLE user_snapshots (
+    user_id TEXT PRIMARY KEY,
+    plan TEXT NOT NULL,
+    plan_config TEXT NOT NULL,        -- JSON (PlanConfig)
+    current_usage TEXT NOT NULL,      -- JSON (CurrentUsage — Pydantic model_dump_json)
+    billing_period_start TEXT,        -- ISO 8601 or NULL
+    billing_period_end TEXT,
+    snapshot_at TEXT DEFAULT (datetime('now'))
+);
+```
+
+The `current_usage` JSON carries `period_cost`, `session_cost`, per-model
+breakdowns, and the in-flight `reserved_cost` / `reserved_tokens_by_model`
+fields.  `plan_config` uses the sentinel `"__INF__"` for `float('inf')`
+limits (stdlib JSON can't encode infinity).
+
+### Debugging with SQLite
+
+Inspect the database directly for debugging:
+
+```bash
+sqlite3 ~/.paygent/local.db
+
+-- Total events + sync status
+SELECT synced, COUNT(*) FROM usage_events GROUP BY synced;
+
+-- Recent events for a user
+SELECT id, model, total_tokens, cost_total, synced, created_at
+FROM usage_events WHERE user_id = 'user_123'
+ORDER BY timestamp DESC LIMIT 10;
+
+-- Cost breakdown by model
+SELECT model, SUM(total_tokens) AS tokens, ROUND(SUM(cost_total), 4) AS cost
+FROM usage_events WHERE user_id = 'user_123' GROUP BY model;
+
+-- Stuck unsynced events
+SELECT COUNT(*) FROM usage_events WHERE synced = 0;
+
+-- Snapshot for a user
+SELECT user_id, plan, current_usage FROM user_snapshots WHERE user_id = 'user_123';
+```
+
+## Coding standards
+
+- **Python 3.10+.**  Use the newer union syntax (`str | None`, not
+  `Optional[str]`) everywhere.
+- **Pydantic v2** for all data models.  Use `PrivateAttr` for fields
+  that must not serialize (e.g. locks).
+- **Logging**: use `logging.getLogger("paygent")` for SDK code,
+  `"paygent_api"` for backend code.  No `print` statements.
+- **Fail-open on every path that intercepts an LLM call.**  Every try
+  block in `patcher.py`, `wrap()`, and `awrap()` should either return
+  the original response or re-raise `PaygentLimitExceeded` — never
+  propagate internal errors into the dev's call stack.
+- **Every test verifies both the happy path AND the fail-open path**
+  when applicable.
+- **UUIDs for event IDs** (`uuid4()`).  These are idempotency keys on
+  the backend — duplicates are silently ignored.
+- **Docstrings on every public method.**
+- **pytest + pytest-asyncio** for testing.  Mock external services in
+  unit tests; no real API calls below the e2e tier.
+
+## Known gotchas
+
+### Shutdown hang on some test files
+
+A few SDK test files (`test_wrap.py`, `test_callbacks.py`,
+`test_multi_call.py`, `test_sqlite_storage.py`) run to completion but
+pytest hangs on interpreter shutdown, waiting for a background daemon
+thread to join.  If you see "N passed" and then the process stalls, the
+tests passed — just `Ctrl+C`.  Pre-existing issue; tracked as tech debt.
+
+### Multi-process drift
+
+The in-memory cache is per-process.  Multi-worker deployments (Gunicorn
+with `workers > 1`, multi-replica Kubernetes) drift between refreshes.
+See the [README "Known Limitations"](./README.md#known-limitations)
+section for the math and mitigations.
+
+### `datetime.utcnow()` deprecation
+
+The codebase uses `datetime.utcnow()` in several places.  Python 3.12+
+deprecates this in favor of `datetime.now(timezone.utc)`.  Currently
+fine on Python 3.10/3.11.  Revisit when we bump the minimum supported
+Python version.
+
+### Thread safety of `_sessions` dict
+
+The cache dict is protected from concurrent iteration via snapshotting
+(`list(self._sessions.items())`).  Per-user state is now protected by
+the per-user lock introduced with the reservation pattern.  The
+remaining gap is pure dict mutation concurrency — single-op mutations
+are safe under the GIL, but compound check-then-set patterns would need
+`_user_locks_lock` (used only for lazy lock creation).  Not a production
+risk today.
+
+## Release process
+
+Paygent is published to PyPI as the `paygent` package.
+
+### Before release
+
+1. Run the full test suite and make sure it's green:
+   ```bash
+   cd sdk && venv/bin/python -m pytest tests/ -q
+   cd ../backend && venv/bin/python -m pytest tests/ -q
+   ./tests/e2e/run_e2e.sh
+   ```
+2. Bump `version` in `sdk/pyproject.toml` (semantic versioning).
+3. Update any version references in docs.
+4. Commit + tag: `git tag v<version> && git push --tags`.
+
+### Publishing to TestPyPI first (recommended)
+
+TestPyPI is a sandbox with the same API as PyPI.  Always verify the
+package installs and imports correctly before pushing to real PyPI —
+once a version is published to real PyPI it cannot be re-uploaded
+(even after yanking).
+
+1. Create accounts on [TestPyPI](https://test.pypi.org) and [PyPI](https://pypi.org).
+2. Generate API tokens on each, stored in `~/.pypirc`:
+   ```ini
+   [distutils]
+   index-servers = pypi testpypi
+
+   [pypi]
+   username = __token__
+   password = pypi-...
+
+   [testpypi]
+   repository = https://test.pypi.org/legacy/
+   username = __token__
+   password = pypi-...
+   ```
+3. Install build tools:
+   ```bash
+   cd sdk
+   venv/bin/pip install build twine
+   ```
+4. Build:
+   ```bash
+   rm -rf dist/
+   venv/bin/python -m build
+   ```
+5. Verify the artifacts:
+   ```bash
+   venv/bin/twine check dist/*
+   unzip -l dist/paygent-*.whl   # spot-check the wheel contents
+   ```
+6. Upload to TestPyPI:
+   ```bash
+   venv/bin/twine upload --repository testpypi dist/*
+   ```
+7. Test-install into a clean venv:
+   ```bash
+   python -m venv /tmp/test-paygent
+   /tmp/test-paygent/bin/pip install \
+       --index-url https://test.pypi.org/simple/ \
+       --extra-index-url https://pypi.org/simple/ \
+       paygent
+   /tmp/test-paygent/bin/python -c "
+   from paygent import Paygent, paygent_context, PlanConfig
+   pg = Paygent.init()
+   print('OK:', pg.is_initialized)
+   pg.shutdown()
+   "
+   ```
+
+### Publishing to PyPI
+
+Once the TestPyPI smoke passes:
+
+```bash
+cd sdk
+venv/bin/twine upload dist/*
+```
+
+### Post-publish
+
+- Visit `https://pypi.org/project/paygent/` — verify the README renders
+  correctly.
+- `pip install paygent` into a fresh venv and run a quick smoke.
+- Announce the release (changelog, blog, etc.).

paygent-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Paygent
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.