lutflow 0.1.0__tar.gz

lutflow-0.1.0/.gitignore

@@ -0,0 +1,250 @@
+# Lutflow .gitignore
+# Enterprise MLOps Platform
+# =========================
+
+# ============================================
+# OS Generated Files
+# ============================================
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+*.swp
+*.swo
+*~
+
+# ============================================
+# IDE / Editor
+# ============================================
+.idea/
+.vscode/
+*.sublime-workspace
+*.sublime-project
+.cursor/
+.claude/
+.cursorrules
+
+# ============================================
+# Environment & Secrets
+# ============================================
+.env
+.env.demo
+.env.local
+.env.*.local
+*.env
+.envrc
+.secrets
+secrets/
+*.pem
+*.key
+credentials*.json
+
+# ============================================
+# Go
+# ============================================
+*.exe
+*.exe~
+*.dll
+*.so
+*.dylib
+bin/
+services/*/bin/
+services/*/tmp/
+*.test
+*.out
+coverage.html
+vendor/
+go.work.sum
+
+# ============================================
+# Python
+# ============================================
+__pycache__/
+*.py[cod]
+*$py.class
+.venv/
+venv/
+ENV/
+env/
+.python-version
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+pip-log.txt
+pip-delete-this-directory.txt
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.ruff_cache/
+uv.lock
+.ipynb_checkpoints
+
+# ============================================
+# Node.js / Next.js
+# ============================================
+node_modules/
+.pnpm-store/
+apps/web/.next/
+apps/web/out/
+apps/web/build/
+.turbo/
+.vercel/
+
+# ============================================
+# Docker
+# ============================================
+docker/data/
+*.log
+
+# ============================================
+# Terraform
+# ============================================
+.terraform/
+*.tfstate
+*.tfstate.*
+*.tfvars
+!example.tfvars
+.terraform.lock.hcl
+
+# ============================================
+# ML Artifacts (use MinIO/S3)
+# ============================================
+*.h5
+*.hdf5
+*.pkl
+*.pickle
+*.joblib
+*.model
+*.pt
+*.pth
+*.onnx
+/models/          # Root-level ML models dir only — NOT services/*/models (Go packages)
+artifacts/
+mlruns/
+luts/
+
+# ============================================
+# Logs & Debug
+# ============================================
+logs/
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+# ============================================
+# Testing
+# ============================================
+coverage/
+.nyc_output/
+test-results/
+playwright-report/
+
+# ============================================
+# Local Development / Temporary Files
+# ============================================
+backup/
+*.bak
+*.tmp
+*.temp
+quick_test.py
+demo_*.py
+test_*.py
+!services/**/test_*.py
+!services/**/tests/
+
+# ============================================
+# Documentation (Internal Only - Root Level)
+# Keep docs/ folder for public documentation
+# ============================================
+/AUDIT_*.md
+/AUDITORIA_*.md
+/*COMPLETE*.md
+/*PROGRESS*.md
+/*REPORT*.md
+/MEGA_PROMPT_*.md
+/PLAN_MAESTRO*.md
+/compass_artifact*.md
+/INFORME_*.md
+/ESTADO_*.md
+/EXECUTION_PLAN*.md
+/RELEASE_*.txt
+/SPRINT_*.md
+/VERIFICATION_*.md
+/VERIFICACION_*.md
+/VERIFICADO*.md
+/VAULT_*.md
+/QA_*.md
+/TESTING_GUIDE.md
+/COMPREHENSIVE_*.md
+/BENTOML_*.md
+/OPERACIONALIZACION_*.md
+/PCPO_*.md
+/FLYWHEEL_*.md
+/LUTFLOW_*.md
+!/LUTFLOW_GROUP_B_TECHNICAL_REPORT.md
+!/LUTFLOW_S0_GONOGO_REPORT.md
+/Refactorizaci*.md
+/FASE_*.md
+/SISTEMA_*.md
+/info.md
+/test-vault.sh
+
+# ============================================
+# Transcriptions & Research
+# ============================================
+transcrip_AWS_AI/
+
+# ============================================
+# Images (except docs)
+# ============================================
+*.png
+*.jpg
+*.jpeg
+*.gif
+!docs/**/*.png
+!docs/**/*.jpg
+
+# ============================================
+# Local Scripts (Windows)
+# ============================================
+*.bat
+start-lutflow.ps1
+
+# ============================================
+# MCP Config (Local)
+# ============================================
+.mcp.json
+
+# ============================================
+# Local SDK / Tooling Downloads
+# ============================================
+google-cloud-sdk/
+google-cloud-sdk-*.tar.gz

lutflow-0.1.0/CHANGELOG.md

@@ -0,0 +1,139 @@
+# Changelog
+
+All notable changes to the Lutflow SDK will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-05-15
+
+### Changed
+
+- First stable release — exits alpha
+- Development status updated to `5 - Production/Stable`
+- All 3 version strings (`pyproject.toml`, `__init__.py`, CLI) bumped to `0.1.0`
+
+### Fixed
+
+- `test_cli.py`: version assertion updated from `0.1.0a5` → `0.1.0a6` (test was hardcoded to stale version)
+- `test_tinyfish_real.py`: mock for live API call updated to correctly simulate async submit→poll flow; spot price updated to reflect current RunPod cached rate ($0.44/hr)
+
+## [0.1.0a6] - 2026-03-31
+
+### Fixed
+
+- Version consistency: `pyproject.toml` and `__init__.py` bumped to `0.1.0a6` after `a5` was published
+- Minor internal cleanup for stable release preparation
+
+## [0.1.0a5] - 2026-03-30
+
+### Fixed
+
+- **P0**: `lutflow.__version__` was stuck at `0.1.0a2` while `pyproject.toml` and CLI reported `0.1.0a4`
+- **P0**: Anthropic dependency version mismatch — `[anthropic]` extra now requires `>=1.0.0` (was `>=0.18.0`)
+- **P0**: CHANGELOG duplicate `0.1.0a3`/`0.1.0a4` sections collapsed
+- **P0**: `demo-search --live` flag was dead code — `fetch_model_benchmarks_with_session` now accepts `quick` parameter
+- **P0**: Removed unused `_endpoint()` helper in CLI
+- **P1**: Gemini `wrap()` now passes full `Client` for unified cloud reporting (was only `BudgetGuard`)
+- **P1**: `recommend()` source metadata reflects actual data provenance instead of API key presence
+- **P1**: `compare_with_neo4j()` guards against missing `"name"` key in Neo4j dicts
+- **P1**: `deploy` command now shows actual HTTP errors for 4xx/5xx instead of fake offline success
+
+### Added
+
+- 24 tests for PCPO module (`CostPredictor`, `PredictiveBudgetGuard`, `PredictionResult`)
+- 15 tests for OpenAI wrapper (token counting, chat completions, embeddings, budget enforcement)
+- 17 tests for Anthropic wrapper (messages, streaming, model normalization)
+- 7 tests for Client cloud reporting and version consistency
+- 4 integration smoke test suites (73 tests total): imports, CLI, wrappers, TinyFish
+- Test for Gemini `wrap()` passing full Client
+- Test for `deploy` HTTP error handling
+
+### Changed
+
+- Total tests: 231 (up from 109)
+- All 3 version strings (`pyproject.toml`, `__init__.py`, `cli.py`) now stay in sync with a consistency test
+
+## [0.1.0a4] - 2026-03-29
+
+### Added
+
+- **Model Intelligence**: New TinyFish integration for HuggingFace Leaderboard model benchmarks
+- `fetch_model_benchmarks(task, max_params_b, quick)` - Fetch model benchmarks from HuggingFace
+- `enrich_with_pricing(benchmarks, gpu_type)` - Add GPU pricing and VRAM estimates to benchmarks
+- `recommend(task, budget_usd_per_hour, gpu_type, quick)` - Get top model recommendation within budget
+- New dataclasses: `ModelBenchmark`, `EnrichedBenchmark`, `ModelRecommendation`
+- `ModelIntelligenceEvent` dataclass for Kafka publishing
+- `publish_model_intelligence_to_kafka()` function with mock support when Kafka not configured
+- Cached benchmarks for 3 tasks: tabular-classification, text-classification, tabular-regression
+- Task aliases: "classification" -> "text-classification", "tabular" -> "tabular-classification"
+- CLI command: `lutflow recommend --task TEXT --budget FLOAT --gpu TEXT [--live] [--tenant TEXT]`
+- CLI output includes "Knowledge graph updated: 1 new ModelIntelligence node → Neo4j"
+- 24 new tests for model benchmark and Kafka functionality
+
+### Changed
+
+- Documentation links now point to PyPI (https://pypi.org/project/lutflow/) instead of docs.lutflow.dev
+- CLI help text updated with PyPI documentation URL
+- Website link changed to lutflow.dev
+
+## [0.1.0a3] - 2026-03-29
+
+Skipped — version published incorrectly to PyPI, immediately replaced by 0.1.0a4.
+
+## [0.1.0a2] - 2026-03-29
+
+### Added
+
+- Google Gemini wrapper (gemini-2.5-flash, gemini-2.5-pro, gemini-2.0-flash, gemini-1.5-flash, gemini-1.5-pro, gemini-1.0-pro)
+- `pip install lutflow[gemini]` for Google AI support
+- Gemini pricing table (input/output per 1K tokens)
+- Multi-GPU cached prices in TinyFish (L4, A100-80GB, H100-80GB, T4)
+- GPU type aliases in TinyFish ("l4" -> "nvidia-l4", "a100" -> "nvidia-a100-80gb")
+- `as_dict()` method on GPUPrice and GPUPricingResult for JSON serialization
+- `is_live` property on GPUPricingResult to check if any price is live
+- `quick=True` parameter for TinyFish to use cached prices instantly (recommended for demos)
+- Documentation: Confluent Kafka/Flink/Tableflow architecture
+- 13 new tests for Gemini wrapper (including gemini-2.5 normalization)
+- 18 new tests for enhanced TinyFish integration (including quick mode)
+
+### Changed
+
+- **BREAKING**: Default `on_budget_exceeded` strategy changed from `SELF_KILL` to `RAISE_ERROR`
+  - This is safer for new users who may not expect their process to be killed
+  - Use `on_budget_exceeded=BudgetStrategy.SELF_KILL` to restore previous behavior
+- CLI commands now show `[OFFLINE MODE]` when Lutflow API is unreachable
+  - Previously showed misleading success messages
+- CLI `watch` command now shows `[SIMULATED DATA]` header
+  - Clarifies that data is simulated until connected to Lutflow Cloud
+- Removed `pydantic` from core dependencies (~30MB lighter install)
+- README updated with Confluent AI Accelerator Cohort 3 and TinyFish Accelerator mentions
+- TinyFish prices now sorted by spot price (cheapest first)
+- TinyFish source field changed from "cached_fallback" to "cached" for clarity
+
+### Fixed
+
+- CLI `deploy` no longer prints fake "Kill path: ACTIVE" when API is unreachable
+- CLI `status` no longer prints hardcoded fake data when API is unreachable
+- CLI `kill` no longer prints fake "kubectl delete deployment executed" when API is unreachable
+
+### Notes
+
+- TinyFish live price fetching can take 1-3 minutes per provider due to complex JavaScript sites
+- Use `quick=True` for instant cached prices (recommended for demos and CI/CD)
+- Cached prices are updated weekly and are accurate for most use cases
+
+## [0.1.0a1] - 2026-03-28
+
+### Added
+
+- Initial alpha release
+- `Client` class for budget-aware LLM API usage
+- OpenAI wrapper (`chat.completions`, `embeddings`)
+- Anthropic wrapper (`messages`, `stream`)
+- Four budget strategies: `RAISE_ERROR`, `WARN_ONLY`, `CALLBACK`, `SELF_KILL`
+- Token-based pricing for 13 models (OpenAI, Anthropic, Google)
+- GPU-time pricing for 5 GPU types
+- TinyFish integration for real-time GPU price discovery
+- CLI commands: `lookup`, `deploy`, `status`, `watch`, `kill`
+- Local-only mode (no Lutflow Cloud required)

lutflow-0.1.0/DEMO_SCRIPT_FINAL.py

@@ -0,0 +1,238 @@
+#!/usr/bin/env python3
+"""
+DEMO_SCRIPT_FINAL.py — TinyFish Accelerator x Google for Startups video demo.
+
+This script demonstrates Lutflow's GPU Financial Firewall capabilities:
+1. TinyFish GPU price lookup (works with cached fallback)
+2. Budget enforcement with Google Gemini
+3. Cost tracking across multiple API calls
+
+REQUIREMENTS:
+- pip install lutflow[gemini]
+- GOOGLE_API_KEY environment variable (for Gemini API calls)
+- TINYFISH_API_KEY environment variable (optional, for live prices)
+
+CONTINGENCY PLAN (if something fails in live demo):
+- If TinyFish fails: cached prices will be shown (still looks good)
+- If Gemini fails: the budget enforcement still works with simulation
+- If budget doesn't trigger: lower the budget_usd
+
+Run: python DEMO_SCRIPT_FINAL.py
+"""
+
+import os
+import sys
+
+# ==============================================================================
+# CONFIGURATION — Adjust these for the demo
+# ==============================================================================
+DEMO_BUDGET_USD = 0.00008  # triggers enforcement around 13-15 Gemini 2.5 Flash calls
+DEMO_MODEL = "gemini-2.5-flash"  # Latest fast model for demo
+DEMO_MAX_CALLS = 20  # Safety limit
+
+# ==============================================================================
+# PART 1: TinyFish GPU Price Lookup
+# ==============================================================================
+def demo_tinyfish_lookup():
+    """Demonstrate TinyFish GPU price discovery."""
+    print()
+    print("=" * 55)
+    print("  Step 1/3: GPU Price Lookup (powered by TinyFish)")
+    print("=" * 55)
+    print()
+    
+    from lutflow.tinyfish import TinyFishClient
+    
+    tf = TinyFishClient()
+    
+    # Use quick=True for instant results (cached prices)
+    # Set quick=False and increase timeout for live prices (takes 1-3 min/provider)
+    result = tf.fetch_all_prices(gpu_type="nvidia-l4", quick=True)
+    
+    mode = "LIVE" if result.is_live else "CACHED"
+    print(f"  Source: {mode} prices")
+    print()
+    
+    for p in result.prices:
+        marker = " <- CHEAPEST" if p == result.cheapest else ""
+        print(f"  {p.provider:<12} ${p.spot_usd_per_hour:.2f}/hr{marker}")
+    
+    print()
+    if result.cheapest:
+        runtime = result.budget_runtime_minutes(0.05)
+        print(f"  $0.05 budget = ~{runtime:.0f} min on {result.cheapest.provider}")
+    print()
+    
+    return result
+
+
+# ==============================================================================
+# PART 2: Budget Enforcement with Gemini
+# ==============================================================================
+def demo_budget_enforcement():
+    """Demonstrate budget enforcement with Google Gemini."""
+    print("=" * 55)
+    print("  Step 2/3: Budget Enforcement with Google Gemini")
+    print("=" * 55)
+    print()
+    
+    gemini_key = os.environ.get("GOOGLE_API_KEY") or os.environ.get("GEMINI_API_KEY")
+    if not gemini_key:
+        print("  GOOGLE_API_KEY not set - running in simulation mode")
+        print()
+        return demo_budget_enforcement_simulated()
+    
+    try:
+        import google.generativeai as genai
+    except ImportError:
+        print("  google-generativeai not installed")
+        print("  Run: pip install lutflow[gemini]")
+        print()
+        return demo_budget_enforcement_simulated()
+    
+    from lutflow import Client, BudgetStrategy, BudgetExceededError
+    
+    genai.configure(api_key=gemini_key)
+    model = genai.GenerativeModel(DEMO_MODEL)
+    
+    print(f"  Budget: ${DEMO_BUDGET_USD:.2f}")
+    print(f"  Model: {DEMO_MODEL}")
+    print(f"  Strategy: RAISE_ERROR")
+    print()
+    
+    client = Client(
+        tenant_id="tinyfish-demo",
+        budget_usd=DEMO_BUDGET_USD,
+        on_budget_exceeded=BudgetStrategy.RAISE_ERROR,
+    )
+    
+    wrapped = client.wrap(model)
+    
+    print(f"  {'Call':<6} {'Spent':<12} {'Remaining':<12} Response")
+    print("  " + "-" * 50)
+    
+    try:
+        for i in range(1, DEMO_MAX_CALLS + 1):
+            response = wrapped.generate_content(
+                f"In one sentence, what is the number {i}?"
+            )
+            
+            text = response.text[:40].replace("\n", " ") if response.text else ""
+            print(
+                f"  {i:<6} "
+                f"${client.accumulated_cost_usd:<11.6f} "
+                f"${client.remaining_budget_usd:<11.6f} "
+                f"{text}..."
+            )
+            
+    except BudgetExceededError as e:
+        print()
+        print("  " + "=" * 50)
+        print("  BUDGET ENFORCED")
+        print(f"  Spent:  ${e.spent_usd:.6f}")
+        print(f"  Budget: ${e.budget_usd:.2f}")
+        print("  " + "=" * 50)
+        print()
+        return True
+        
+    except Exception as e:
+        print(f"\n  Error: {type(e).__name__}: {e}")
+        return False
+    
+    print("\n  Budget was not exceeded within the call limit.")
+    return False
+
+
+def demo_budget_enforcement_simulated():
+    """Simulated budget enforcement without real API calls."""
+    from lutflow import Client, BudgetStrategy, BudgetExceededError
+    
+    print(f"  Budget: ${DEMO_BUDGET_USD:.2f}")
+    print(f"  Strategy: RAISE_ERROR")
+    print()
+    
+    client = Client(
+        tenant_id="tinyfish-demo",
+        budget_usd=DEMO_BUDGET_USD,
+        on_budget_exceeded=BudgetStrategy.RAISE_ERROR,
+    )
+    
+    print("  Simulating Gemini API calls...")
+    print()
+    print(f"  {'Call':<6} {'Spent':<12} {'Remaining':<12} Status")
+    print("  " + "-" * 40)
+    
+    # Simulate costs similar to gemini-2.0-flash
+    simulated_cost_per_call = 0.003  # ~$0.003 per call
+    
+    try:
+        for i in range(1, DEMO_MAX_CALLS + 1):
+            client.add_cost(simulated_cost_per_call)
+            
+            status = "OK" if client.budget_utilization_percent < 80 else "WARNING"
+            
+            print(
+                f"  {i:<6} "
+                f"${client.accumulated_cost_usd:<11.6f} "
+                f"${client.remaining_budget_usd:<11.6f} "
+                f"{status}"
+            )
+            
+    except BudgetExceededError as e:
+        print()
+        print("  " + "=" * 40)
+        print("  BUDGET ENFORCED (simulated)")
+        print(f"  Spent:  ${e.spent_usd:.6f}")
+        print(f"  Budget: ${e.budget_usd:.2f}")
+        print("  " + "=" * 40)
+        print()
+        return True
+    
+    return False
+
+
+# ==============================================================================
+# PART 3: Summary
+# ==============================================================================
+def demo_summary():
+    """Print demo summary."""
+    print("=" * 55)
+    print("  Step 3/3: Summary")
+    print("=" * 55)
+    print()
+    print("  What you just saw:")
+    print("    - TinyFish found cheapest GPU provider")
+    print("    - Gemini tracked every token automatically")
+    print("    - Budget enforced before damage occurred")
+    print()
+    print("  Lookup -> Flow -> Value")
+    print()
+    print("  pip install lutflow[gemini]")
+    print("  pypi.org/project/lutflow")
+    print()
+
+
+# ==============================================================================
+# MAIN
+# ==============================================================================
+def main():
+    print()
+    print("=" * 55)
+    print("  LUTFLOW — GPU Financial Firewall")
+    print("  TinyFish Accelerator x Google for Startups")
+    print("=" * 55)
+    
+    # Part 1: TinyFish lookup
+    demo_tinyfish_lookup()
+    
+    # Part 2: Budget enforcement
+    success = demo_budget_enforcement()
+    
+    # Part 3: Summary
+    demo_summary()
+    
+    return 0 if success else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())