cyris 0.1.0__tar.gz

cyris-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cyris
+
+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.

cyris-0.1.0/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.4
+Name: cyris
+Version: 0.1.0
+Summary: The system of record for AI agent decisions. Log every LLM call your agents make, hash-chain the audit trail, and answer compliance questionnaires from real data.
+Author-email: Cyris <hello@cyrisai.dev>
+License: MIT
+Project-URL: Homepage, https://cyrisai.dev
+Project-URL: Repository, https://github.com/ultimatem7/Cyris
+Project-URL: Issues, https://github.com/ultimatem7/Cyris/issues
+Keywords: ai,audit,compliance,hipaa,llm,observability,openai,anthropic,agents,monitoring
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Healthcare Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+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: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Monitoring
+Classifier: Topic :: System :: Logging
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.20.0
+Provides-Extra: openai
+Requires-Dist: openai>=1.0.0; extra == "openai"
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.18.0; extra == "anthropic"
+Provides-Extra: all
+Requires-Dist: openai>=1.0.0; extra == "all"
+Requires-Dist: anthropic>=0.18.0; extra == "all"
+Dynamic: license-file
+
+# cyris
+
+The system of record for AI agent decisions.
+
+## Install
+
+```bash
+pip install cyris
+```
+
+## Usage
+
+```python
+import cyris
+cyris.init(api_key="your-key")
+# That's it. Every OpenAI/Anthropic call is now logged.
+```
+
+## Manual logging
+
+```python
+cyris.log_call(provider="openai", model="gpt-4o", input_text="Hello", output_text="Hi there")
+```
+
+## Sessions
+
+```python
+with cyris.session("my-workflow") as sid:
+    # all calls inside this block share the same session_id
+    ...
+```
+
+## CLI
+
+```bash
+cyris login       # authenticate via browser
+cyris whoami      # show current identity
+cyris status      # check API connectivity
+cyris logout      # remove saved credentials
+```

cyris-0.1.0/README.md

@@ -0,0 +1,40 @@
+# cyris
+
+The system of record for AI agent decisions.
+
+## Install
+
+```bash
+pip install cyris
+```
+
+## Usage
+
+```python
+import cyris
+cyris.init(api_key="your-key")
+# That's it. Every OpenAI/Anthropic call is now logged.
+```
+
+## Manual logging
+
+```python
+cyris.log_call(provider="openai", model="gpt-4o", input_text="Hello", output_text="Hi there")
+```
+
+## Sessions
+
+```python
+with cyris.session("my-workflow") as sid:
+    # all calls inside this block share the same session_id
+    ...
+```
+
+## CLI
+
+```bash
+cyris login       # authenticate via browser
+cyris whoami      # show current identity
+cyris status      # check API connectivity
+cyris logout      # remove saved credentials
+```

cyris-0.1.0/cyris/__init__.py

@@ -0,0 +1,5 @@
+from .core import init, log_call, log_override, log_event
+from .session import session
+from .version import __version__
+
+__all__ = ["init", "log_call", "log_override", "log_event", "session", "__version__"]

cyris-0.1.0/cyris/buffer.py

@@ -0,0 +1,126 @@
+"""
+Thread-safe event buffer with background flushing.
+
+Events are queued in memory and periodically POSTed to the Cyris
+``/ingest-batch`` endpoint by a daemon thread.  The design guarantees:
+
+* **No perceptible latency** -- callers return immediately after enqueue.
+* **No data loss on exit** -- ``atexit`` flushes remaining events.
+* **Silent failures** -- network errors go to *stderr*, never raise.
+"""
+
+import atexit
+import json
+import sys
+import threading
+import time
+from typing import Any, Dict, List, Optional
+
+_queue: List[Dict[str, Any]] = []
+_lock = threading.Lock()
+_flush_event = threading.Event()
+
+_api_url: Optional[str] = None
+_api_key: Optional[str] = None
+_thread: Optional[threading.Thread] = None
+_shutdown_flag = threading.Event()
+
+_FLUSH_INTERVAL_S = 5
+_FLUSH_BATCH_SIZE = 10
+
+
+# ---------------------------------------------------------------------- #
+# Public API                                                              #
+# ---------------------------------------------------------------------- #
+
+def configure(api_url: str, api_key: str) -> None:
+    """Set the target endpoint and API key.  Called once from ``init()``."""
+    global _api_url, _api_key
+    _api_url = api_url.rstrip("/")
+    _api_key = api_key
+
+
+def start() -> None:
+    """Spin up the background flush thread (idempotent)."""
+    global _thread
+    if _thread is not None and _thread.is_alive():
+        return
+
+    _shutdown_flag.clear()
+    _thread = threading.Thread(target=_flush_loop, daemon=True, name="cyris-buffer")
+    _thread.start()
+    atexit.register(shutdown)
+
+
+def add_event(event: Dict[str, Any]) -> None:
+    """Enqueue an event dict for later transmission."""
+    with _lock:
+        _queue.append(event)
+        if len(_queue) >= _FLUSH_BATCH_SIZE:
+            _flush_event.set()
+
+
+def flush() -> None:
+    """Immediately flush the current queue (best-effort)."""
+    _do_flush()
+
+
+def shutdown() -> None:
+    """Signal the background thread to stop and flush remaining events."""
+    _shutdown_flag.set()
+    _flush_event.set()  # wake the thread so it exits promptly
+    if _thread is not None and _thread.is_alive():
+        _thread.join(timeout=5)
+    _do_flush()
+
+
+# ---------------------------------------------------------------------- #
+# Internals                                                               #
+# ---------------------------------------------------------------------- #
+
+def _flush_loop() -> None:
+    """Background loop: flush every *_FLUSH_INTERVAL_S* or on signal."""
+    while not _shutdown_flag.is_set():
+        _flush_event.wait(timeout=_FLUSH_INTERVAL_S)
+        _flush_event.clear()
+        _do_flush()
+
+
+def _do_flush() -> None:
+    """Drain the queue and POST to the ingest endpoint."""
+    with _lock:
+        if not _queue:
+            return
+        batch = list(_queue)
+        _queue.clear()
+
+    if not _api_url or not _api_key:
+        return
+
+    try:
+        import requests  # deferred so import-time stays fast
+
+        url = f"{_api_url}/ingest-batch"
+        headers = {
+            "Authorization": f"Bearer {_api_key}",
+            "Content-Type": "application/json",
+        }
+        # Server expects { "events": [...] }. Sending a raw list returns 400.
+        payload = json.dumps({"events": batch})
+        resp = requests.post(url, data=payload, headers=headers, timeout=10)
+
+        # Surface non-2xx in stderr so users notice silently-dropped events.
+        if not (200 <= resp.status_code < 300):
+            try:
+                print(
+                    f"[cyris] flush rejected: HTTP {resp.status_code} {resp.text[:200]}",
+                    file=sys.stderr,
+                )
+            except Exception:
+                pass
+    except Exception as exc:  # noqa: BLE001 -- intentionally broad
+        # Silent failure: never crash the host application.
+        try:
+            print(f"[cyris] flush error: {exc}", file=sys.stderr)
+        except Exception:
+            pass

cyris-0.1.0/cyris/cli.py

@@ -0,0 +1,202 @@
+"""
+CLI entry point for the ``cyris`` command.
+
+Subcommands
+-----------
+    cyris login     -- authenticate via browser OAuth flow
+    cyris logout    -- remove saved credentials
+    cyris whoami    -- display the current identity
+    cyris status    -- check API connectivity
+    cyris --version -- print package version
+"""
+
+import argparse
+import http.server
+import json
+import secrets
+import sys
+import threading
+import urllib.parse
+import webbrowser
+from typing import Optional
+
+from .credentials import delete_credentials, load_credentials, save_credentials
+from .version import __version__
+
+_DEFAULT_API_URL = "https://cyrisai.dev/api/v1"
+
+
+# ====================================================================== #
+# CLI dispatcher                                                          #
+# ====================================================================== #
+
+def main(argv: Optional[list] = None) -> None:
+    parser = argparse.ArgumentParser(
+        prog="cyris",
+        description="Cyris -- the system of record for AI agent decisions.",
+    )
+    parser.add_argument(
+        "--version", "-V",
+        action="version",
+        version=f"cyris {__version__}",
+    )
+
+    sub = parser.add_subparsers(dest="command")
+
+    # login
+    login_p = sub.add_parser("login", help="Authenticate with Cyris")
+    login_p.add_argument("--api-url", default=_DEFAULT_API_URL, help="API base URL")
+
+    # logout
+    sub.add_parser("logout", help="Remove saved credentials")
+
+    # whoami
+    sub.add_parser("whoami", help="Show current identity")
+
+    # status
+    status_p = sub.add_parser("status", help="Check API connectivity")
+    status_p.add_argument("--api-url", default=None, help="Override API URL")
+
+    args = parser.parse_args(argv)
+
+    if args.command == "login":
+        _cmd_login(args.api_url)
+    elif args.command == "logout":
+        _cmd_logout()
+    elif args.command == "whoami":
+        _cmd_whoami()
+    elif args.command == "status":
+        _cmd_status(args.api_url)
+    else:
+        parser.print_help()
+
+
+# ====================================================================== #
+# Subcommand implementations                                              #
+# ====================================================================== #
+
+def _cmd_login(api_url: str) -> None:
+    """Open the browser for OAuth, start a local HTTP server for callback."""
+    api_url = api_url.rstrip("/")
+    state = secrets.token_urlsafe(32)
+
+    # Pick an ephemeral port for the callback server.
+    result: dict = {}
+    server_ready = threading.Event()
+
+    class _CallbackHandler(http.server.BaseHTTPRequestHandler):
+        def do_GET(self) -> None:  # noqa: N802
+            query = urllib.parse.urlparse(self.path).query
+            params = urllib.parse.parse_qs(query)
+
+            received_state = params.get("state", [None])[0]
+            api_key = params.get("api_key", [None])[0]
+            org_name = params.get("org_name", [""])[0]
+            email = params.get("email", [""])[0]
+
+            if received_state != state:
+                self.send_response(400)
+                self.end_headers()
+                self.wfile.write(b"State mismatch -- login aborted.")
+                return
+
+            result["api_key"] = api_key
+            result["org_name"] = org_name
+            result["email"] = email
+
+            self.send_response(200)
+            self.send_header("Content-Type", "text/html")
+            self.end_headers()
+            self.wfile.write(
+                b"<html><body><h2>Login successful!</h2>"
+                b"<p>You can close this tab.</p></body></html>"
+            )
+
+        def log_message(self, fmt, *args) -> None:  # noqa: ARG002
+            pass  # silence server logs
+
+    server = http.server.HTTPServer(("127.0.0.1", 0), _CallbackHandler)
+    port = server.server_address[1]
+
+    def _serve() -> None:
+        server_ready.set()
+        server.handle_request()  # single request then stop
+
+    t = threading.Thread(target=_serve, daemon=True)
+    t.start()
+    server_ready.wait()
+
+    callback = f"http://localhost:{port}"
+    login_url = f"{api_url}/auth/cli?callback={urllib.parse.quote(callback)}&state={state}"
+
+    print(f"Opening browser for login...\n{login_url}")
+    webbrowser.open(login_url)
+
+    t.join(timeout=120)
+    server.server_close()
+
+    if result.get("api_key"):
+        save_credentials(
+            api_key=result["api_key"],
+            api_url=api_url,
+            org_name=result.get("org_name", ""),
+            email=result.get("email", ""),
+        )
+        print(f"Logged in as {result.get('email', 'unknown')} ({result.get('org_name', '')})")
+    else:
+        print("Login failed or timed out.", file=sys.stderr)
+        sys.exit(1)
+
+
+def _cmd_logout() -> None:
+    delete_credentials()
+    print("Logged out. Credentials removed.")
+
+
+def _cmd_whoami() -> None:
+    creds = load_credentials()
+    if not creds:
+        print("Not logged in. Run `cyris login` first.")
+        return
+    print(f"Email:   {creds.get('email', '(not set)')}")
+    print(f"Org:     {creds.get('org_name', '(not set)')}")
+    print(f"API URL: {creds.get('api_url', _DEFAULT_API_URL)}")
+
+
+def _cmd_status(api_url_override: Optional[str]) -> None:
+    creds = load_credentials()
+    api_url = api_url_override or (creds and creds.get("api_url")) or _DEFAULT_API_URL
+    api_key = (creds and creds.get("api_key")) or None
+
+    if not api_key:
+        print("No API key found. Run `cyris login` first.", file=sys.stderr)
+        sys.exit(1)
+
+    api_url = api_url.rstrip("/")
+
+    try:
+        import requests
+
+        resp = requests.get(
+            f"{api_url}/agents",
+            headers={"Authorization": f"Bearer {api_key}"},
+            timeout=10,
+        )
+        if resp.status_code == 200:
+            data = resp.json()
+            agents = data if isinstance(data, list) else data.get("agents", [])
+            print(f"Connected to {api_url}")
+            print(f"Agents: {len(agents)}")
+        else:
+            print(f"API returned HTTP {resp.status_code}", file=sys.stderr)
+            sys.exit(1)
+    except ImportError:
+        print("The `requests` package is required. pip install requests", file=sys.stderr)
+        sys.exit(1)
+    except Exception as exc:
+        print(f"Connection failed: {exc}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

cyris-0.1.0/cyris/core.py

@@ -0,0 +1,216 @@
+"""
+Core initialisation and logging functions for the Cyris SDK.
+
+This module exposes the four public helpers re-exported from ``cyris``:
+
+    cyris.init()           -- configure the SDK
+    cyris.log_call()       -- record an LLM invocation
+    cyris.log_override()   -- record a human override
+    cyris.log_event()      -- record an arbitrary audit event
+"""
+
+import hashlib
+import os
+import sys
+import time
+import uuid
+from typing import Any, Dict, List, Optional
+
+from . import buffer
+from .credentials import load_credentials
+from .fingerprint import generate_fingerprints
+from .phi import detect_phi
+from .session import get_current_session
+
+# ------------------------------------------------------------------ #
+# Module-level config (populated by ``init``)                        #
+# ------------------------------------------------------------------ #
+
+_config: Dict[str, Any] = {
+    "api_key": None,
+    "api_url": "https://cyrisai.dev/api/v1",
+    "agent_name": None,
+    "auto_patch": True,
+    "initialised": False,
+}
+
+
+def _resolve_api_key(api_key: Optional[str]) -> Optional[str]:
+    """Resolve the API key from (in order) parameter, env var, saved creds."""
+    if api_key:
+        return api_key
+
+    env_key = os.environ.get("CYRIS_API_KEY")
+    if env_key:
+        return env_key
+
+    creds = load_credentials()
+    if creds and creds.get("api_key"):
+        return creds["api_key"]
+
+    return None
+
+
+# ------------------------------------------------------------------ #
+# init                                                                #
+# ------------------------------------------------------------------ #
+
+def init(
+    api_key: Optional[str] = None,
+    api_url: Optional[str] = None,
+    agent_name: Optional[str] = None,
+    auto_patch: bool = True,
+) -> None:
+    """Initialise the Cyris SDK.
+
+    Parameters
+    ----------
+    api_key : str, optional
+        Cyris API key.  Falls back to ``CYRIS_API_KEY`` env var, then to
+        saved credentials at ``~/.cyris/credentials``.
+    api_url : str, optional
+        Base URL of the Cyris API (default ``https://cyrisai.dev/api/v1``).
+    agent_name : str, optional
+        Logical name of the agent being instrumented.
+    auto_patch : bool
+        When ``True`` (default), monkey-patch OpenAI and Anthropic client
+        libraries so every call is automatically logged.
+    """
+    resolved_key = _resolve_api_key(api_key)
+    if not resolved_key:
+        try:
+            print(
+                "[cyris] WARNING: no API key found. "
+                "Pass api_key=, set CYRIS_API_KEY, or run `cyris login`.",
+                file=sys.stderr,
+            )
+        except Exception:
+            pass
+
+    _config["api_key"] = resolved_key
+    _config["api_url"] = (api_url or _config["api_url"]).rstrip("/")
+    _config["agent_name"] = agent_name
+    _config["auto_patch"] = auto_patch
+    _config["initialised"] = True
+
+    # Configure and start the background buffer.
+    if resolved_key:
+        buffer.configure(_config["api_url"], resolved_key)
+        buffer.start()
+
+    # Monkey-patch provider libraries when requested.
+    if auto_patch:
+        try:
+            from . import patchers
+            patchers.apply_patches()
+        except Exception as exc:  # noqa: BLE001
+            try:
+                print(f"[cyris] auto-patch failed: {exc}", file=sys.stderr)
+            except Exception:
+                pass
+
+
+# ------------------------------------------------------------------ #
+# log_call                                                            #
+# ------------------------------------------------------------------ #
+
+def log_call(
+    provider: str = "unknown",
+    model: str = "unknown",
+    input_text: str = "",
+    output_text: str = "",
+    input_tokens: int = 0,
+    output_tokens: int = 0,
+    latency_ms: float = 0.0,
+    status: str = "success",
+    error_message: Optional[str] = None,
+    session_id: Optional[str] = None,
+    agent_name: Optional[str] = None,
+) -> None:
+    """Record a single LLM invocation.
+
+    Safe to call even before ``init()`` -- events will be silently
+    dropped if no API key is configured.
+    """
+    try:
+        input_hash = hashlib.sha256(input_text.encode("utf-8")).hexdigest() if input_text else None
+        output_hash = hashlib.sha256(output_text.encode("utf-8")).hexdigest() if output_text else None
+
+        phi_result = detect_phi(input_text + " " + output_text)
+        fingerprints = generate_fingerprints(output_text)
+
+        event = {
+            "event_type": "llm_call",
+            "id": str(uuid.uuid4()),
+            "timestamp": time.time(),
+            "provider": provider,
+            "model": model,
+            "input_tokens": input_tokens,
+            "output_tokens": output_tokens,
+            "latency_ms": latency_ms,
+            "status": status,
+            "error_message": error_message,
+            "input_hash": input_hash,
+            "output_hash": output_hash,
+            "phi_detected": phi_result["detected"],
+            "phi_fields": phi_result["fields_found"],
+            "fingerprints": fingerprints,
+            "session_id": session_id or get_current_session(),
+            "agent_name": agent_name or _config.get("agent_name"),
+        }
+
+        buffer.add_event(event)
+    except Exception:  # noqa: BLE001
+        # NEVER crash the host application.
+        pass
+
+
+# ------------------------------------------------------------------ #
+# log_override                                                        #
+# ------------------------------------------------------------------ #
+
+def log_override(
+    invocation_id: str,
+    reason: str = "",
+    override_by: str = "",
+) -> None:
+    """Record a human override of an agent's decision."""
+    try:
+        event = {
+            "event_type": "override",
+            "id": str(uuid.uuid4()),
+            "timestamp": time.time(),
+            "invocation_id": invocation_id,
+            "reason": reason,
+            "override_by": override_by,
+            "session_id": get_current_session(),
+            "agent_name": _config.get("agent_name"),
+        }
+        buffer.add_event(event)
+    except Exception:  # noqa: BLE001
+        pass
+
+
+# ------------------------------------------------------------------ #
+# log_event                                                           #
+# ------------------------------------------------------------------ #
+
+def log_event(
+    event_type: str = "custom",
+    description: str = "",
+    metadata: Optional[Dict[str, Any]] = None,
+) -> None:
+    """Record an arbitrary audit event."""
+    try:
+        event = {
+            "event_type": event_type,
+            "id": str(uuid.uuid4()),
+            "timestamp": time.time(),
+            "description": description,
+            "metadata": metadata or {},
+            "session_id": get_current_session(),
+            "agent_name": _config.get("agent_name"),
+        }
+        buffer.add_event(event)
+    except Exception:  # noqa: BLE001
+        pass