forecost 0.1.0__tar.gz

forecost-0.1.0/.forecost.toml.example

@@ -0,0 +1,5 @@
+# This file is created by `forecost init`
+# Add .forecost.toml to your .gitignore
+project_name = "your-project"
+path = "."
+created_at = "2026-01-01T00:00:00+00:00"

forecost-0.1.0/.github/FUNDING.yml

@@ -0,0 +1 @@
+github: ArivunidhiA

forecost-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,46 @@
+name: Bug Report
+description: Report a bug in forecost
+labels: [bug]
+body:
+  - type: input
+    id: version
+    attributes:
+      label: forecost version
+      placeholder: "0.1.0"
+    validations:
+      required: true
+  - type: input
+    id: python-version
+    attributes:
+      label: Python version
+      placeholder: "3.12"
+    validations:
+      required: true
+  - type: input
+    id: os
+    attributes:
+      label: Operating System
+      placeholder: "macOS 15, Ubuntu 24.04, Windows 11"
+    validations:
+      required: true
+  - type: textarea
+    id: description
+    attributes:
+      label: What happened?
+      description: Describe the bug clearly.
+    validations:
+      required: true
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to reproduce
+      description: How can we reproduce the issue?
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      description: What did you expect to happen?
+    validations:
+      required: true

forecost-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,25 @@
+name: Feature Request
+description: Suggest a new feature for forecost
+labels: [enhancement]
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: What feature would you like?
+    validations:
+      required: true
+  - type: textarea
+    id: use-case
+    attributes:
+      label: Use case
+      description: Why do you need this feature?
+    validations:
+      required: true
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed solution
+      description: How would you implement this?
+    validations:
+      required: false

forecost-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,52 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - run: pip install -e ".[dev]"
+      - run: ruff check forecost/ tests/
+      - run: ruff format --check forecost/ tests/
+
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+        os: [ubuntu-latest, macos-latest]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - run: pip install -e ".[dev,forecast]"
+      - run: pytest tests/ -v --tb=short -x
+
+  smoke:
+    runs-on: ubuntu-latest
+    needs: [lint, test]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install .
+      - run: forecost --version
+      - run: forecost --help
+      - run: forecost demo

forecost-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,51 @@
+name: Release to PyPI
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  test-install:
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install dist/*.whl
+      - run: forecost --version
+      - run: forecost demo
+
+  publish:
+    needs: [build, test-install]
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/forecost
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

forecost-0.1.0/.gitignore

@@ -0,0 +1,55 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+
+# Virtual environments
+venv/
+.venv/
+env/
+
+# Environment variables
+.env
+*.env.local
+
+# Databases
+*.db
+*.sqlite3
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Node.js / Frontend
+node_modules/
+.next/
+out/
+
+# Test
+.pytest_cache/
+htmlcov/
+.coverage
+coverage.xml
+
+# Logs
+*.log
+
+# Cursor
+.cursor/
+
+# forecost
+.forecost.toml
+.forecost/

forecost-0.1.0/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/).
+
+## [0.1.0] - 2026-03-12
+
+### Changed
+- **Branding:** PyPI package, CLI, and Python import are **`forecost`**. Project config is **`.forecost.toml`**; local data lives under **`~/.forecost/`**. Disable tracking with **`FORECOST_DISABLED=1`** (replaces older env var names).
+
+### Added
+- `forecost init` -- Initialize project with heuristic or LLM-powered scope analysis
+- `forecost forecast` -- Adaptive exponential smoothing cost forecast with Rich output
+- `forecost status` -- One-line project status
+- `forecost track` -- View recent tracked LLM calls
+- `forecost serve` -- Local HTTP API server
+- `forecost demo` -- See forecost in action with sample data
+- `forecost watch` -- Live cost dashboard in terminal
+- `forecost optimize` -- Model optimization suggestions
+- `forecost reset` -- Reset project baseline or full data
+- `auto_track()` -- Zero-code-change cost tracking via httpx interception
+- `log_call()` -- Manual cost logging
+- `log_stream_usage()` -- Streaming response cost logging
+- `@track_cost` decorator for function-level tracking
+- `FORECOST_DISABLED` environment variable to disable tracking
+- `forecost.disable()` function
+- Support for 90+ models across OpenAI, Anthropic, Google, Mistral, DeepSeek, xAI, Meta, Cohere
+- Self-correcting pricing via ratio-based forecasting
+- Forecast stability metric (replaces misleading MAPE)
+- Budget alerts and CI exit codes (`--exit-code`)
+- Optional Textual TUI dashboard (`pip install forecost[tui]`)
+- PEP 561 py.typed marker for type checking support

forecost-0.1.0/CLAUDE.md

@@ -0,0 +1,46 @@
+# forecost Development Guide
+
+## What This Project Is
+forecost is a local-first Python CLI tool that forecasts LLM API costs.
+It uses adaptive exponential smoothing (upgrading to a 3-model ensemble)
+on daily spend data to predict total project cost.
+
+## Architecture Rules
+- All source code lives in forecost/ (flat layout, not src/)
+- CLI commands are in forecost/commands/ — each is a thin wrapper calling core logic
+- Core modules: db.py (SQLite), pricing.py (static prices), forecaster.py (ensemble),
+  interceptor.py (httpx patching), tracker.py (public API), scope.py (heuristic analyzer)
+- Tests live in tests/ and tests/benchmarks/
+- pyproject.toml uses hatchling build backend
+
+## Iron Rules (Never Violate These)
+1. The interceptor must NEVER break the host application's HTTP requests.
+   All tracking logic is wrapped in try/except. Real errors propagate, tracking errors are swallowed.
+2. calculate_forecast(save=False) is the default. Only the explicit `forecast` command saves.
+   Status, serve, and JSON output do NOT save forecast rows.
+3. No network calls for pricing data. All prices are hardcoded in FALLBACK_PRICING dict.
+4. The WriteQueue worker thread has its OWN SQLite connection. Never share connections across threads.
+5. .forecost.toml uses relative paths (path = "."). Never write absolute paths to config files.
+
+## Testing Rules
+- Run pytest tests/ -v after every change
+- The forecaster is the most important module — test accuracy with synthetic data
+- The interceptor is the most dangerous module — test that it never breaks httpx
+- Mock all HTTP calls in tests. Never make real API calls.
+- Benchmarks in tests/benchmarks/ can be slower but must pass
+
+## What NOT To Do
+- Don't add a web dashboard or frontend
+- Don't add database migrations (schema-less metadata JSON column handles extensibility)
+- Don't add authentication or multi-user support
+- Don't add real-time pricing fetches from the internet
+- Don't add heavy ML dependencies (statsmodels is the ceiling)
+- Don't use except Exception: pass — always log errors to ~/.forecost/error.log
+
+## Key Commands
+pip install -e ".[dev,forecast]"   # Install for development
+pytest tests/ -v                    # Run all tests
+pytest tests/benchmarks/ -v         # Run accuracy benchmarks
+ruff check forecost/ tests/           # Lint
+forecost demo                         # See it working with sample data
+python -m build                     # Build for PyPI

forecost-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,39 @@
+# Contributing to forecost
+
+Thanks for your interest in contributing to forecost.
+
+## Development Setup
+
+```bash
+git clone https://github.com/ArivunidhiA/forecost.git
+cd forecost
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+## Running Tests
+
+```bash
+pytest tests/ -v
+```
+
+## Code Style
+
+We use ruff for linting and formatting:
+
+```bash
+ruff check forecost/ tests/
+ruff format forecost/ tests/
+```
+
+## Pull Request Process
+
+1. Fork the repo and create a feature branch
+2. Make your changes with tests
+3. Ensure `ruff check` and `pytest` pass
+4. Submit a PR against `main`
+
+## Reporting Issues
+
+Use the GitHub issue templates for bugs and feature requests.

forecost-0.1.0/LICENSE

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

forecost-0.1.0/PKG-INFO

@@ -0,0 +1,249 @@
+Metadata-Version: 2.4
+Name: forecost
+Version: 0.1.0
+Summary: Know exactly what your AI project will cost. Local-first LLM cost forecasting that learns from your usage.
+Project-URL: Homepage, https://github.com/ArivunidhiA/forecost
+Project-URL: Issues, https://github.com/ArivunidhiA/forecost/issues
+Author: Forecost contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: anthropic,cli,cost,forecast,llm,openai
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: click>=8.0
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: rich>=13.0
+Requires-Dist: tomli>=2.0.0; python_version < '3.11'
+Provides-Extra: all
+Requires-Dist: litellm>=1.0; extra == 'all'
+Requires-Dist: numpy>=1.24; extra == 'all'
+Requires-Dist: plotext>=5.0; extra == 'all'
+Requires-Dist: statsmodels>=0.14; extra == 'all'
+Requires-Dist: textual>=0.50; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: numpy>=1.24; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: statsmodels>=0.14; extra == 'dev'
+Provides-Extra: forecast
+Requires-Dist: numpy>=1.24; extra == 'forecast'
+Requires-Dist: statsmodels>=0.14; extra == 'forecast'
+Provides-Extra: llm
+Requires-Dist: litellm>=1.0; extra == 'llm'
+Provides-Extra: tui
+Requires-Dist: plotext>=5.0; extra == 'tui'
+Requires-Dist: textual>=0.50; extra == 'tui'
+Description-Content-Type: text/markdown
+
+# forecost
+
+**Know what your AI project will cost. Before you build it.**
+
+[![PyPI version](https://img.shields.io/pypi/v/forecost.svg)](https://pypi.org/project/forecost/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Python 3.10+ required. forecost is in Alpha: APIs may change and some features are experimental.
+
+See `forecost demo` for a live preview.
+
+## The Problem
+
+LLM API costs are unpredictable. You prototype with GPT-4, ship to production, and the first month's bill arrives as a surprise. Most teams have no way to forecast spend until it's too late. forecost fixes this by learning from your actual usage and giving you accurate cost projections before you scale.
+
+## Quick Start
+
+Full walkthrough from install to forecast:
+
+```bash
+pip install forecost
+cd your-project
+forecost init
+```
+
+Add to your app's entry point (before any LLM calls):
+
+```python
+import forecost
+forecost.auto_track()
+```
+
+Call `auto_track()` early, before any httpx usage. If your app imports httpx before forecost, the interceptor may not attach correctly.
+
+Run your app as usual. After building usage for a few days:
+
+```bash
+forecost forecast
+```
+
+## See It in Action
+
+`forecost demo` runs a forecast with sample data and no setup. Use it to see the full output before tracking your own project.
+
+## Auto-Tracking
+
+Non-streaming calls are tracked automatically. No decorators, no manual logging.
+
+**Streaming limitation:** forecost cannot intercept streaming responses automatically. You must call `log_stream_usage` after consuming the stream. Pass the accumulated response dict containing a `usage` key (and optionally `model` for identification):
+
+```python
+import forecost
+forecost.auto_track()
+
+# Example: OpenAI streaming
+response = client.chat.completions.create(model="gpt-4", messages=[...], stream=True)
+accumulated = {"usage": {"prompt_tokens": 0, "completion_tokens": 0}, "model": "gpt-4"}
+for chunk in response:
+    if chunk.usage:
+        accumulated["usage"] = {"prompt_tokens": chunk.usage.prompt_tokens,
+                               "completion_tokens": chunk.usage.completion_tokens}
+    if chunk.model:
+        accumulated["model"] = chunk.model
+forecost.log_stream_usage(accumulated)
+```
+
+For Anthropic, use `input_tokens` and `output_tokens` instead of `prompt_tokens` and `completion_tokens`.
+
+## Manual Tracking
+
+For fine-grained control, use the `@track_cost` decorator or `log_call`:
+
+```python
+import forecost
+
+@forecost.track_cost(provider="openai")
+def call_gpt(prompt: str):
+    return openai.chat.completions.create(model="gpt-4", messages=[{"role": "user", "content": prompt}])
+
+# Or log calls manually
+forecost.log_call(model="gpt-4", tokens_in=500, tokens_out=200, provider="openai")
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `forecost init` | Initialize project and create `.forecost.toml` config |
+| `forecost init --budget X` | Set a budget cap in USD |
+| `forecost forecast` | Show cost forecast in terminal |
+| `forecost forecast --output markdown` | Output forecast as Markdown |
+| `forecost forecast --output csv` | Output forecast as CSV |
+| `forecost forecast --tui` | Interactive TUI dashboard (requires `pip install forecost[tui]`) |
+| `forecost forecast --json` | JSON output for CI/scripts |
+| `forecost forecast --brief` | One-line summary (same format as `status`) |
+| `forecost forecast --exit-code` | Exit 1 if projected over budget, 2 if actual over budget (for CI) |
+| `forecost status` | One-line summary: spend, projected total, day count, drift status |
+| `forecost track` | View recent tracked LLM calls |
+| `forecost watch` | Live cost dashboard; updates as your app makes calls |
+| `forecost export --format csv` | Export usage data as CSV |
+| `forecost export --format json` | Export usage data as JSON |
+| `forecost demo` | Run forecast with sample data, no setup needed |
+| `forecost optimize` | Suggest cost optimizations based on usage |
+| `forecost reset` | Reset the current project (optionally keep usage logs) |
+| `forecost serve` | Run local API server for programmatic access |
+
+`status` and `forecast --brief` both show the same one-line summary. Use `status` when you only need a quick check; use `forecast --brief` when you want that format in a script or CI pipeline.
+
+## Budget Enforcement
+
+Set a budget at init with `--budget`:
+
+```bash
+forecost init --budget 100
+```
+
+Use `--exit-code` on forecast to fail CI when over budget:
+
+```yaml
+- name: Check LLM Budget
+  run: |
+    pip install forecost
+    forecost forecast --exit-code
+```
+
+Exit codes: 0 = on track, 1 = projected over budget, 2 = actual spend over budget.
+
+## Disabling in Tests
+
+```bash
+FORECOST_DISABLED=1 pytest
+```
+
+Or in code:
+
+```python
+forecost.disable()
+```
+
+## Forecasting Accuracy
+
+forecost uses an ensemble of three statistical forecasting methods (Simple Exponential Smoothing, Damped Trend, and Linear Regression) inspired by the M4 Forecasting Competition, where simple combinations beat complex ML models across 100,000 time series.
+
+| Metric | What it means | Typical result |
+|--------|---------------|----------------|
+| MASE | Are we beating a naive guess? | < 1.0 after 5 days |
+| MAE | How many dollars could we be off? | Decreases as data grows |
+| 80% interval | Will the real cost land here? | ~80% of the time |
+| 95% interval | Conservative budget range | ~95% of the time |
+
+Install the ensemble engine for best results: `pip install forecost[forecast]`
+
+The base install uses a simpler exponential moving average that works without additional dependencies.
+
+## Why forecost?
+
+| Feature | forecost | LiteLLM | Helicone | LangSmith |
+|---------|--------|---------|----------|-----------|
+| Cost tracking | Yes | Yes | Yes | Yes |
+| Cost forecasting | Yes | No | No | No |
+| Prediction intervals | Yes | No | No | No |
+| Zero infrastructure | Yes | No (proxy) | No (cloud) | No (cloud) |
+| Zero overhead on requests | Yes (post-response) | No (proxy latency) | No (proxy latency) | No (SDK wrapper) |
+| Local-only / private | Yes | Partial | No | No |
+| pip install, 2 lines | Yes | SDK wrapper | Proxy setup | SDK setup |
+| Free forever | Yes | Freemium | Freemium | $39/seat/mo |
+
+Minimal footprint: 3 runtime dependencies (click, rich, httpx), under 3MB.
+
+## Data Storage
+
+- **Usage and forecasts:** `~/.forecost/costs.db` (SQLite). All projects share this database.
+- **Project config:** `.forecost.toml` in your project root. Contains project name, baseline days, and optional budget.
+
+## Glossary
+
+| Term | Meaning |
+|------|---------|
+| **Confidence levels** | How reliable the forecast is based on data volume: low (0 days), medium-low (1-3), medium (4-7), high (8-14), very-high (15+). More usage data yields higher confidence. |
+| **Drift status** | Whether spend is trending above or below the baseline: `on_track`, `over_budget`, or `under_budget`. Based on recent daily burn ratios. |
+| **MASE** | Mean Absolute Scaled Error. Compares forecast accuracy to a naive "yesterday = tomorrow" guess. MASE < 1.0 means the forecast beats the naive baseline. |
+| **Stability** | How much the forecast changes between runs: `converged` (< 5% change), `stabilizing` (5-15%), or `adjusting` (> 15%). |
+| **Prediction intervals** | 80% and 95% ranges around the projected total. The real cost will fall within the 80% interval about 80% of the time. |
+
+## Local API Server
+
+`forecost serve` starts a local HTTP server (default port 8787) for programmatic access:
+
+| Endpoint | Description |
+|----------|-------------|
+| `GET /api/health` | Health check. Returns `{"status": "ok"}`. |
+| `GET /api/forecast` | Full forecast result (same as `forecost forecast --json`). |
+| `GET /api/status` | Project status: active days, actual spend, baseline info. |
+| `GET /api/costs` | Recent usage logs. |
+
+Run from your project directory so forecost can find `.forecost.toml`.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT