cygnos-capture-proxy 0.1.0__tar.gz

cygnos_capture_proxy-0.1.0/LICENSE

@@ -0,0 +1,88 @@
+Cygnos Proprietary Software License
+
+Copyright (c) 2026 Cygnos AI Private Limited. All rights reserved.
+
+1. DEFINITIONS
+
+"Software" means the Cygnos client software distributed in this package,
+including its source code, object code, and accompanying documentation.
+
+"Licensor" means Cygnos AI Private Limited, a company incorporated under
+the laws of India with its registered office at Jaipur, Rajasthan, India.
+
+"Service" means the Cygnos hosted service operated by Licensor.
+
+"You" means the individual or legal entity exercising rights under this
+License.
+
+2. GRANT OF LICENSE
+
+Subject to Your compliance with this License and with a current written
+agreement with Licensor governing use of the Service, Licensor grants You a
+non-exclusive, non-transferable, non-sublicensable, revocable license to
+install and use the Software solely to transmit telemetry from Your systems
+to the Service, and for no other purpose.
+
+3. RESTRICTIONS
+
+You may not:
+
+  (a) copy the Software except as reasonably necessary for installation and
+      backup;
+  (b) modify, adapt, translate, or create derivative works of the Software;
+  (c) reverse engineer, decompile, or disassemble the Software, except to
+      the extent this restriction is unenforceable under applicable law;
+  (d) distribute, sublicense, rent, lease, lend, sell, or otherwise transfer
+      the Software to any third party;
+  (e) remove or obscure any proprietary notice contained in the Software; or
+  (f) use the Software to develop, or to assist any third party in
+      developing, a product or service competitive with the Service.
+
+4. OWNERSHIP
+
+The Software is licensed, not sold. Licensor retains all right, title, and
+interest in and to the Software, including all intellectual property rights
+therein. No rights are granted to You except as expressly set out in this
+License.
+
+5. THIRD-PARTY COMPONENTS
+
+The Software may incorporate third-party open source components, each
+governed by its own license terms. Those terms govern those components to
+the extent they conflict with this License.
+
+6. TERMINATION
+
+This License terminates automatically upon Your breach of any of its terms,
+and terminates when Your written agreement with Licensor governing use of
+the Service terminates or expires. Upon termination You must cease all use
+of the Software and delete all copies in Your possession or control.
+
+7. NO WARRANTY
+
+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.
+
+8. LIMITATION OF LIABILITY
+
+TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, IN NO EVENT SHALL
+LICENSOR 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.
+
+9. PRECEDENCE
+
+Where You have a written agreement with Licensor governing use of the
+Service, that agreement controls in the event of any conflict with this
+License.
+
+10. GOVERNING LAW
+
+This License is governed by the laws of India, without regard to its
+conflict of law principles. The courts at Jaipur, Rajasthan, India shall
+have exclusive jurisdiction, save where a written agreement between You and
+Licensor governing use of the Service provides otherwise, in which case that
+agreement controls.
+
+Contact: hello@cygnos.ai

cygnos_capture_proxy-0.1.0/PKG-INFO

@@ -0,0 +1,194 @@
+Metadata-Version: 2.4
+Name: cygnos-capture-proxy
+Version: 0.1.0
+Summary: Local pass-through capture endpoint for AI API traffic — the first Cygnos capture source.
+Author-email: Cygnos AI Private Limited <hello@cygnos.ai>
+License-Expression: LicenseRef-Proprietary
+Project-URL: Homepage, https://cygnos.ai
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: starlette>=0.37
+Requires-Dist: uvicorn>=0.29
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2
+Requires-Dist: cygnos-shared[schema]>=0.1.0
+Provides-Extra: brotli
+Requires-Dist: brotli>=1.1; extra == "brotli"
+Provides-Extra: zstd
+Requires-Dist: zstandard>=0.22; extra == "zstd"
+Provides-Extra: all
+Requires-Dist: brotli>=1.1; extra == "all"
+Requires-Dist: zstandard>=0.22; extra == "all"
+Dynamic: license-file
+
+# Connect your AI usage — Cygnos Capture Proxy
+
+A lightweight local process that gives Cygnos visibility into your AI API usage.
+It is a **pass-through reader, never a modifier**: it forwards every request to
+the provider **unchanged** and emits one usage event per call to Cygnos. It
+never filters, blocks, rewrites, retries, or injects anything. Claude Code is
+the first supported client; more capture sources are coming.
+
+> A bug in Cygnos is a bad dashboard, never a bad prompt — that's the whole
+> design. The proxy only *observes*.
+
+---
+
+## Prerequisites (2 minutes)
+
+1. A **Cygnos account** and an **organisation that has been approved** (you'll
+   see the dashboard, not the "access under review" screen).
+2. An **API key**: in the dashboard, open **API Keys** → *Create key* → copy the
+   `cygnos_sk_…` value. You only see it once. (Events from an unapproved org are
+   rejected, so make sure your org is approved first.)
+
+## Install
+
+```bash
+pip install cygnos-capture-proxy
+```
+
+Python 3.10 or newer. That is the whole install — no Cygnos repository, no clone,
+no build step. It brings its own dependencies and puts a `cygnos-capture` command
+on your PATH.
+
+gzip and deflate response streams are read out of the box. If your traffic comes
+back brotli- or zstd-encoded, add the optional decoders (without them those
+responses still pass through untouched — only the token counts on those events
+are missed):
+
+```bash
+pip install "cygnos-capture-proxy[all]"
+```
+
+## Configure (the two env vars)
+
+```bash
+export CYGNOS_API_KEY="cygnos_sk_your_key_here"
+export CYGNOS_INGEST_URL="https://<your-cygnos-host>/events"
+```
+
+## Run
+
+```bash
+cygnos-capture                 # or: python -m cygnos_capture_proxy
+```
+
+You'll see a startup line like:
+
+```
+Cygnos Capture Proxy on http://127.0.0.1:8788 → upstream https://api.anthropic.com → ingest https://…/events (session 1f2e…)
+```
+
+It binds to `127.0.0.1` only — nothing is exposed on your network.
+
+### The binding banner — read it before you walk away
+
+Immediately after that line the proxy checks, against your Cygnos backend, whether
+your key actually resolves to an organisation, and says so in plain words. This is
+the one thing worth reading at startup, because a broken key is otherwise invisible:
+your AI tools keep working perfectly while nothing reaches your dashboard.
+
+A good binding looks like this — the organisation named is the tenant your events
+will land under, so check it is the one you meant:
+
+```
+Cygnos capture binding: OK — Your Cygnos API key was accepted.
+  Organisation: Acme Robotics (org_2f9c…)
+  Events will be sent to https://…/events
+```
+
+A broken one is loud and tells you what to do about it:
+
+```
+───────────────────────────────────────────────────────────────────────────
+CYGNOS CAPTURE IS NOT BOUND — captured events will NOT reach your dashboard.
+
+  What is wrong: Cygnos does not recognise this API key, or it has been revoked.
+                 Every event will be rejected.
+  What to do:    Check CYGNOS_API_KEY against the API Keys page. A key is shown once
+                 at creation; if it was mangled or revoked, create a new one.
+
+  Your AI tools are UNAFFECTED. This proxy will keep forwarding every request
+  to the provider normally. Only Cygnos capture is broken.
+───────────────────────────────────────────────────────────────────────────
+```
+
+A failed binding does **not** stop the proxy, on purpose: a Cygnos problem must never
+become an outage in your day. It starts, it shouts, and it keeps forwarding your
+traffic. If you would rather it refused to start than run unbound, set
+`CYGNOS_REQUIRE_BINDING=1`.
+
+## Point Claude Code at it
+
+In the **same terminal** where you'll run Claude Code:
+
+```bash
+export ANTHROPIC_BASE_URL=http://localhost:8788
+```
+
+Now use Claude Code exactly as normal. Your traffic flows through the proxy to
+Anthropic untouched; Cygnos receives a usage event per request.
+
+## Confirm it's working
+
+- The proxy's **startup banner** is printed and the process is still running.
+- The terminal running Claude Code has `ANTHROPIC_BASE_URL` set
+  (`echo $ANTHROPIC_BASE_URL` → `http://localhost:8788`).
+- Your **first event** appears in the Cygnos dashboard shortly after your first
+  Claude Code message.
+
+**Am I being captured right now?** Capture happens only when *both* are true:
+the proxy process is running, **and** the terminal you launched Claude Code from
+had `ANTHROPIC_BASE_URL` exported. A different terminal (or after `unset`) talks
+to Anthropic directly with no capture.
+
+## Stop / undo
+
+```bash
+unset ANTHROPIC_BASE_URL     # Claude Code instantly talks to Anthropic directly again
+# then Ctrl-C the proxy process
+```
+
+This is the one-line escape hatch — see the transport note below.
+
+## Troubleshooting
+
+Run the proxy with `CYGNOS_CAPTURE_DEBUG=1` to log, per request, what it saw on
+the wire (status, content-type, content-encoding, first bytes) and what it
+extracted (model, tokens, status) — no prompt or response content is logged:
+
+```bash
+CYGNOS_CAPTURE_DEBUG=1 python -m cygnos_capture_proxy
+```
+
+If events show zero tokens, the debug log's `content_encoding` and `first_bytes`
+lines are the place to look.
+
+---
+
+## Security & transport — read this once, honestly
+
+- **The proxy sits in your request path.** While `ANTHROPIC_BASE_URL` points at
+  it, your Claude Code traffic goes *through* this local process. If the process
+  dies mid-request, that one in-flight request fails — the **one-line escape** is
+  `unset ANTHROPIC_BASE_URL` (Claude Code then talks to Anthropic directly). Event
+  emission is fully decoupled and fire-and-forget, so a Cygnos outage never
+  affects your traffic.
+- **Your Anthropic API key never reaches Cygnos.** It passes straight through to
+  Anthropic. Cygnos receives only a one-way **hashed fingerprint** (16 hex chars)
+  so you can tell keys apart — never the key itself.
+- **Your prompts and responses never leave your machine.** This proxy reads a
+  prompt only to forward it to Anthropic, and the response is never parsed for
+  text at all. Cygnos receives a one-way SHA-256 hash of the prompt and a
+  content-free risk verdict — PII reported by category name ("email"), never the
+  value; sensitive terms reported as a count, never the terms. This is enforced
+  in code: the proxy refuses to transmit any event carrying content.

cygnos_capture_proxy-0.1.0/README.md

@@ -0,0 +1,163 @@
+# Connect your AI usage — Cygnos Capture Proxy
+
+A lightweight local process that gives Cygnos visibility into your AI API usage.
+It is a **pass-through reader, never a modifier**: it forwards every request to
+the provider **unchanged** and emits one usage event per call to Cygnos. It
+never filters, blocks, rewrites, retries, or injects anything. Claude Code is
+the first supported client; more capture sources are coming.
+
+> A bug in Cygnos is a bad dashboard, never a bad prompt — that's the whole
+> design. The proxy only *observes*.
+
+---
+
+## Prerequisites (2 minutes)
+
+1. A **Cygnos account** and an **organisation that has been approved** (you'll
+   see the dashboard, not the "access under review" screen).
+2. An **API key**: in the dashboard, open **API Keys** → *Create key* → copy the
+   `cygnos_sk_…` value. You only see it once. (Events from an unapproved org are
+   rejected, so make sure your org is approved first.)
+
+## Install
+
+```bash
+pip install cygnos-capture-proxy
+```
+
+Python 3.10 or newer. That is the whole install — no Cygnos repository, no clone,
+no build step. It brings its own dependencies and puts a `cygnos-capture` command
+on your PATH.
+
+gzip and deflate response streams are read out of the box. If your traffic comes
+back brotli- or zstd-encoded, add the optional decoders (without them those
+responses still pass through untouched — only the token counts on those events
+are missed):
+
+```bash
+pip install "cygnos-capture-proxy[all]"
+```
+
+## Configure (the two env vars)
+
+```bash
+export CYGNOS_API_KEY="cygnos_sk_your_key_here"
+export CYGNOS_INGEST_URL="https://<your-cygnos-host>/events"
+```
+
+## Run
+
+```bash
+cygnos-capture                 # or: python -m cygnos_capture_proxy
+```
+
+You'll see a startup line like:
+
+```
+Cygnos Capture Proxy on http://127.0.0.1:8788 → upstream https://api.anthropic.com → ingest https://…/events (session 1f2e…)
+```
+
+It binds to `127.0.0.1` only — nothing is exposed on your network.
+
+### The binding banner — read it before you walk away
+
+Immediately after that line the proxy checks, against your Cygnos backend, whether
+your key actually resolves to an organisation, and says so in plain words. This is
+the one thing worth reading at startup, because a broken key is otherwise invisible:
+your AI tools keep working perfectly while nothing reaches your dashboard.
+
+A good binding looks like this — the organisation named is the tenant your events
+will land under, so check it is the one you meant:
+
+```
+Cygnos capture binding: OK — Your Cygnos API key was accepted.
+  Organisation: Acme Robotics (org_2f9c…)
+  Events will be sent to https://…/events
+```
+
+A broken one is loud and tells you what to do about it:
+
+```
+───────────────────────────────────────────────────────────────────────────
+CYGNOS CAPTURE IS NOT BOUND — captured events will NOT reach your dashboard.
+
+  What is wrong: Cygnos does not recognise this API key, or it has been revoked.
+                 Every event will be rejected.
+  What to do:    Check CYGNOS_API_KEY against the API Keys page. A key is shown once
+                 at creation; if it was mangled or revoked, create a new one.
+
+  Your AI tools are UNAFFECTED. This proxy will keep forwarding every request
+  to the provider normally. Only Cygnos capture is broken.
+───────────────────────────────────────────────────────────────────────────
+```
+
+A failed binding does **not** stop the proxy, on purpose: a Cygnos problem must never
+become an outage in your day. It starts, it shouts, and it keeps forwarding your
+traffic. If you would rather it refused to start than run unbound, set
+`CYGNOS_REQUIRE_BINDING=1`.
+
+## Point Claude Code at it
+
+In the **same terminal** where you'll run Claude Code:
+
+```bash
+export ANTHROPIC_BASE_URL=http://localhost:8788
+```
+
+Now use Claude Code exactly as normal. Your traffic flows through the proxy to
+Anthropic untouched; Cygnos receives a usage event per request.
+
+## Confirm it's working
+
+- The proxy's **startup banner** is printed and the process is still running.
+- The terminal running Claude Code has `ANTHROPIC_BASE_URL` set
+  (`echo $ANTHROPIC_BASE_URL` → `http://localhost:8788`).
+- Your **first event** appears in the Cygnos dashboard shortly after your first
+  Claude Code message.
+
+**Am I being captured right now?** Capture happens only when *both* are true:
+the proxy process is running, **and** the terminal you launched Claude Code from
+had `ANTHROPIC_BASE_URL` exported. A different terminal (or after `unset`) talks
+to Anthropic directly with no capture.
+
+## Stop / undo
+
+```bash
+unset ANTHROPIC_BASE_URL     # Claude Code instantly talks to Anthropic directly again
+# then Ctrl-C the proxy process
+```
+
+This is the one-line escape hatch — see the transport note below.
+
+## Troubleshooting
+
+Run the proxy with `CYGNOS_CAPTURE_DEBUG=1` to log, per request, what it saw on
+the wire (status, content-type, content-encoding, first bytes) and what it
+extracted (model, tokens, status) — no prompt or response content is logged:
+
+```bash
+CYGNOS_CAPTURE_DEBUG=1 python -m cygnos_capture_proxy
+```
+
+If events show zero tokens, the debug log's `content_encoding` and `first_bytes`
+lines are the place to look.
+
+---
+
+## Security & transport — read this once, honestly
+
+- **The proxy sits in your request path.** While `ANTHROPIC_BASE_URL` points at
+  it, your Claude Code traffic goes *through* this local process. If the process
+  dies mid-request, that one in-flight request fails — the **one-line escape** is
+  `unset ANTHROPIC_BASE_URL` (Claude Code then talks to Anthropic directly). Event
+  emission is fully decoupled and fire-and-forget, so a Cygnos outage never
+  affects your traffic.
+- **Your Anthropic API key never reaches Cygnos.** It passes straight through to
+  Anthropic. Cygnos receives only a one-way **hashed fingerprint** (16 hex chars)
+  so you can tell keys apart — never the key itself.
+- **Your prompts and responses never leave your machine.** This proxy reads a
+  prompt only to forward it to Anthropic, and the response is never parsed for
+  text at all. Cygnos receives a one-way SHA-256 hash of the prompt and a
+  content-free risk verdict — PII reported by category name ("email"), never the
+  value; sensitive terms reported as a count, never the terms. This is enforced
+  in code: the proxy refuses to transmit any event carrying content.

cygnos_capture_proxy-0.1.0/__init__.py

@@ -0,0 +1,18 @@
+"""
+Cygnos Capture Proxy — a local, pass-through capture endpoint for AI API traffic.
+
+This is the first "capture source" in Cygnos' connect-your-usage portfolio. A
+customer runs it locally; an AI tool points at it via a base-URL override
+(Claude Code's ANTHROPIC_BASE_URL is the first documented client). The proxy
+forwards every request to the provider UNCHANGED and emits one standard Cygnos
+event per completion to the customer's ingestion endpoint.
+
+North-star constraints (see DF1_ONBOARDING.md BI-2):
+  - Pass-through reader, NEVER a modifier — no filter/block/rewrite/inject/retry.
+  - Fail-open, fail-silent — event emission is fire-and-forget and never affects
+    the proxied request. (The proxy is in the request path, so if the *process*
+    dies a single in-flight request drops; the escape is to unset the env var.)
+  - Standard events only — the existing Universal AI Event Schema, no new type.
+  - Keyed ingestion — CYGNOS_API_KEY + CYGNOS_INGEST_URL; the provider key
+    passes through to the provider and never reaches Cygnos (fingerprint only).
+"""

cygnos_capture_proxy-0.1.0/__main__.py

@@ -0,0 +1,74 @@
+"""
+Entry point: `python -m cygnos_capture_proxy`.
+
+Starts the local pass-through capture endpoint on 127.0.0.1:<port>. Point your
+AI tool at it, e.g. for Claude Code:  export ANTHROPIC_BASE_URL=http://localhost:8788
+To stop capturing instantly: unset ANTHROPIC_BASE_URL (Claude Code talks to the
+provider directly again) and Ctrl-C this process.
+"""
+from __future__ import annotations
+
+import logging
+import sys
+
+import uvicorn
+
+from .app import build_app
+from .config import ConfigFileError, config_path, load_config
+from .portcheck import check_or_explain
+
+
+def main() -> None:
+    logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)-8s %(message)s")
+    try:
+        cfg = load_config()
+    except ConfigFileError as exc:
+        # CFG-1 §5 — a config file we cannot trust stops the proxy, and stops it
+        # READABLY. Printed rather than raised: a traceback through json.loads tells
+        # an operator nothing they can act on, while this names the file and the line.
+        # Exit 1 so a supervisor (launchd, systemd, a shell script) sees a failure
+        # rather than a clean stop.
+        print(f"\nCygnos capture proxy did not start.\n\n{exc}\n", file=sys.stderr)
+        raise SystemExit(1)
+    # CAPTURE-1 — the old "CYGNOS_API_KEY is not set" warning lived here and was
+    # the ONLY signal the proxy ever gave about its binding. It has been replaced
+    # by the startup binding check in the app lifespan (see binding.py), which
+    # covers the unset key AND the three failures this could never see: a key
+    # this backend does not recognise, a key whose organisation is not approved,
+    # and a backend that does not answer at all.
+    # CFG-1 — say which file was consulted, even when there was none. An operator
+    # debugging "why is it using that URL" needs to know whether a file is in play at
+    # all; silence about the file is what makes stale-config bugs hard to see.
+    _path = config_path()
+    logging.info(
+        "Cygnos config file: %s",
+        _path if _path.exists() else f"{_path} (not present — environment and defaults only)",
+    )
+    logging.info(
+        "Cygnos Capture Proxy on http://%s:%d → upstream %s → ingest %s (session %s)",
+        cfg.host, cfg.port, cfg.upstream_base_url, cfg.ingest_url, cfg.session_id,
+    )
+    # INIT-1 §6 — refuse to start on a squatted port, LOUDLY.
+    #
+    # uvicorn's own failure here is a raw OSError traceback ending "address already
+    # in use", and the damage is not the ugly traceback. It is the belief it
+    # leaves behind: the operator restarts the proxy after changing their key or
+    # their actor, sees a wall of red they read as a crash, and the OLD proxy is
+    # still running, still capturing, still on the old configuration. They now
+    # believe the restart failed when in fact it never happened — and every event
+    # from that point is stamped with settings nobody thinks are in effect.
+    #
+    # So we look BEFORE binding, name what is holding the port, and say which of
+    # the two cases it is. check_or_explain returns None when the port is free
+    # AND when its own inspection fails, because a diagnostic that cannot run
+    # must never become the reason the proxy will not start (CAPTURE-1).
+    collision = check_or_explain(cfg.host, cfg.port)
+    if collision:
+        print("\n" + "\n".join(collision) + "\n", file=sys.stderr)
+        raise SystemExit(1)
+
+    uvicorn.run(build_app(cfg), host=cfg.host, port=cfg.port, log_level="info")
+
+
+if __name__ == "__main__":
+    main()