Metadata-Version: 2.5
Name: memflow-relay
Version: 0.1.0
Summary: MemFlow Relay — local Gemini proxy with shadow/safe/optimize modes by LamoonAGI
Project-URL: Homepage, https://www.lamoonagi.com/en/memflow/relay/
Project-URL: Documentation, https://www.lamoonagi.com/en/memflow/docs/
Project-URL: Repository, https://github.com/lamoonagi/memflow-relay
Project-URL: Bug Tracker, https://github.com/lamoonagi/memflow-relay/issues
Author-email: LamoonAGI <dev@lamoonagi.com>
License: MIT License
        
        Copyright (c) 2024 LamoonAGI
        
        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.
License-File: LICENSE
Keywords: context-optimizer,gemini,lamoonagi,llm,memflow,proxy
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: anyio>=4.4.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic-settings>=2.3.0
Requires-Dist: pydantic>=2.7.0
Requires-Dist: starlette>=0.37.0
Requires-Dist: typer>=0.12.0
Requires-Dist: uvicorn[standard]>=0.30.0
Provides-Extra: dev
Requires-Dist: coverage>=7.5.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-httpx>=0.30.0; extra == 'dev'
Requires-Dist: pytest>=8.2.0; extra == 'dev'
Requires-Dist: respx>=0.21.0; extra == 'dev'
Description-Content-Type: text/markdown

# MemFlow Relay

> **Research Preview** — MemFlow Relay is currently in research preview. APIs and behaviours may change without prior notice.

**MemFlow Relay** is a local HTTP proxy for Gemini API requests, developed by [LamoonAGI](https://www.lamoonagi.com). It transparently intercepts your Gemini calls and — depending on the configured operating mode — can analyse, optimise, or shadow-test context window usage before forwarding the request to Google Gemini.

---

## Features

- **Shadow mode** — observe without modification; original request is always forwarded unchanged.
- **Safe mode** — apply optimizations only when confidence is high; fall back to original on any doubt.
- **Optimize mode** — apply MemFlow context optimizations and track token savings.
- **Fail-open default** — if the MemFlow optimizer is unreachable or times out, the relay always forwards the original request to Gemini.
- **Credential isolation** — `GEMINI_API_KEY` never leaves your machine; it is never sent to LamoonAGI or MemFlow cloud services.
- **Secret redaction** — all logs, exceptions, and telemetry automatically strip API keys, Bearer tokens, and cookies.
- **Telemetry modes** — `off`, `metrics_only` (default, no prompt content), or `diagnostic`.

---

## Installation

```bash
pip install memflow-relay
```

Requires Python ≥ 3.11.

---

## Quick Start

```bash
# Set credentials
export MEMFLOW_API_KEY="lago_your_key_here"
export GEMINI_API_KEY="your_gemini_key_here"

# Start relay in shadow mode (safe default)
memflow-relay serve

# Verify setup
memflow-relay doctor

# Show live stats
memflow-relay stats
```

Your Gemini SDK base URL should be set to `http://127.0.0.1:8765`.

---

## CLI Commands

| Command | Description |
|---|---|
| `memflow-relay serve` | Start the local proxy (default port 8765) |
| `memflow-relay doctor` | Verify credentials, connectivity, and port availability |
| `memflow-relay test` | Run end-to-end shadow mode verification |
| `memflow-relay stats` | Display analyzed / optimized / bypassed counts and token savings |
| `memflow-relay benchmark` | Run baseline vs optimized Gemini workload comparison |
| `memflow-relay version` | Report package version and research preview status |

---

## Configuration

All configuration is via environment variables. See `.env.example` for a full reference.

| Variable | Default | Description |
|---|---|---|
| `MEMFLOW_API_KEY` | — | LamoonAGI API key (required for optimize/safe modes) |
| `GEMINI_API_KEY` | — | Google Gemini API key (never sent to LamoonAGI) |
| `MEMFLOW_API_URL` | `https://api.lamoonagi.com` | MemFlow optimizer endpoint |
| `MEMFLOW_MODE` | `shadow` | Operating mode: `shadow`, `safe`, `optimize` |
| `MEMFLOW_TELEMETRY` | `metrics_only` | Telemetry level: `off`, `metrics_only`, `diagnostic` |
| `MEMFLOW_PORT` | `8765` | Local proxy port |
| `MEMFLOW_FAIL_OPEN` | `true` | Forward original request if optimizer fails |

---

## Security

See [SECURITY.md](SECURITY.md) for vulnerability disclosure policy.

**Key guarantee:** `GEMINI_API_KEY` is used exclusively to authenticate requests to `generativelanguage.googleapis.com`. It is never included in requests to `api.lamoonagi.com` or any other endpoint.

---

## License

MIT — see [LICENSE](LICENSE).

© 2024 LamoonAGI. MemFlow is a product of LamoonAGI. Powered by LamoonAGI Context VMM technology.
