peekai 0.1.0__tar.gz

peekai-0.1.0/.env.example

@@ -0,0 +1,14 @@
+# PeekAI Demo Environment Variables
+# 
+# Copy this file to .env and fill in your credentials:
+#   cp .env.example .env
+#
+# ⚠️  Never commit .env to version control!
+#     It's already in .gitignore
+
+# Your OpenAI API key (required for demos)
+OPENAI_API_KEY=sk-your-api-key-here
+
+# Optional: Custom base URL for OpenAI-compatible endpoints
+# Default: https://api.openai.com/v1
+OPENAI_BASE_URL=https://api.openai.com/v1

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

@@ -0,0 +1,41 @@
+name: CI
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+
+jobs:
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Lint
+        run: uv run ruff check src/
+
+      - name: Type check
+        run: uv run mypy src/peekai/
+
+      - name: Test
+        run: uv run pytest tests/ -v

peekai-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,41 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*.*.*"   # triggers on v0.1.0, v1.2.3, etc.
+
+jobs:
+  build-and-publish:
+    name: Build and publish
+    runs-on: ubuntu-latest
+    environment: pypi   # matches the trusted publisher environment on PyPI
+
+    permissions:
+      id-token: write   # required for OIDC trusted publishing (no API key needed)
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        # Uses OIDC trusted publishing — no PYPI_API_TOKEN secret needed.
+        # Configure the trusted publisher on PyPI:
+        #   https://pypi.org/manage/account/publishing/
+        #   Publisher: GitHub Actions
+        #   Owner:     peekai
+        #   Repo:      peekai
+        #   Workflow:  publish.yml
+        #   Env:       pypi

peekai-0.1.0/.gitignore

@@ -0,0 +1,211 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   uv.lock is committed for applications, ignored for libraries.
+#   PeekAI is a library/tool — keeping lock out of VCS until v0.1 ships.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# PeekAI
+*.peekai.db
+peekai.db
+.peekai/

peekai-0.1.0/.streamlit/config.toml

@@ -0,0 +1,15 @@
+[theme]
+base = "light"
+primaryColor = "#ff6600"
+backgroundColor = "#f8fafc"
+secondaryBackgroundColor = "#ffffff"
+textColor = "#0f172a"
+
+[server]
+headless = true
+
+[browser]
+gatherUsageStats = false
+
+[logger]
+level = "error"

peekai-0.1.0/BACKLOG.md

@@ -0,0 +1,155 @@
+# PeekAI — Product Backlog
+
+> 👀 Lightweight, local-first observability and debugging for Python AI agents.
+
+---
+
+## How to use this backlog
+
+- Keep this file in `docs/BACKLOG.md` inside your repo
+- Use GitHub Projects as your weekly kanban board
+- Every Sunday: pick tasks for the week and move them to "This Week"
+- Update status here monthly as phases complete
+
+**Status legend:** `⬜ Todo` `🔵 In Progress` `✅ Done`
+
+---
+
+## Phase 0 — Project Setup
+> Goal: clean foundation before any real code
+
+| Status | Task | Priority | Effort |
+|--------|------|----------|--------|
+| ✅ | Set up project structure and folders | High | 30 min |
+| ⬜ | Set up virtual environment | High | 15 min |
+| ✅ | Create `pyproject.toml` with project metadata | High | 30 min |
+| ✅ | Add `.gitignore` for Python + SQLite | High | 10 min |
+| ✅ | Write initial README with vision + install preview | High | 45 min |
+
+---
+
+## Phase 1 — Core SDK (Instrumentation Layer)
+> Goal: capture a real trace from a real OpenAI call
+
+| Status | Task | Priority | Effort |
+|--------|------|----------|--------|
+| ✅ | Create `Span` and `Trace` dataclasses | High | 1 hr |
+| ✅ | Build `Tracer` class with `ContextVar` for async safety | High | 2 hrs |
+| ✅ | Build `Storage` class with SQLite via `sqlite3` | High | 2 hrs |
+| ✅ | Implement OpenAI SDK monkey-patch | High | 3 hrs |
+| ✅ | Implement Anthropic SDK monkey-patch | High | 2 hrs |
+| ✅ | Implement LiteLLM monkey-patch | Medium | 2 hrs |
+| ✅ | Token tracking per span | High | 1 hr |
+| ✅ | Cost calculation per span per model | High | 1 hr |
+| ✅ | Error capture with full context | High | 1 hr |
+| ✅ | `peekai.init()` auto-patches all installed SDKs | High | 1 hr |
+| ✅ | `@peekai.trace()` decorator for agent runs | High | 1 hr |
+| ✅ | Tool call tracking via decorator | Medium | 2 hrs |
+| ✅ | Write unit tests for tracer and storage | Medium | 2 hrs |
+
+---
+
+## Phase 2 — CLI
+> Goal: fully usable without any UI at all
+
+| Status | Task | Priority | Effort |
+|--------|------|----------|--------|
+| ✅ | Set up Typer CLI skeleton | High | 30 min |
+| ✅ | `peekai list` — show last 10 traces | High | 1 hr |
+| ✅ | `peekai view <trace-id>` — pretty print trace | High | 2 hrs |
+| ✅ | `peekai stats` — total cost, tokens, runs | Medium | 1 hr |
+| ✅ | `peekai clear` — wipe local storage | Medium | 30 min |
+| ✅ | `peekai ui` — launch Streamlit UI | High | 30 min |
+| ✅ | Colorized terminal output with `rich` | Medium | 1 hr |
+
+---
+
+## Phase 3 — Streamlit Web UI
+> Goal: something you'd screenshot and post on Twitter
+
+| Status | Task | Priority | Effort |
+|--------|------|----------|--------|
+| ✅ | Trace list view with status, cost, duration | High | 2 hrs |
+| ✅ | Trace detail waterfall view (span by span) | High | 3 hrs |
+| ✅ | Token + cost breakdown per span | High | 1 hr |
+| ✅ | Error highlighting in trace view | High | 1 hr |
+| ✅ | Filter traces by status, model, date | Medium | 2 hrs |
+| ✅ | JSON input/output viewer per span | Medium | 1 hr |
+| ✅ | Total dashboard — runs, cost, tokens over time | Medium | 2 hrs |
+
+---
+
+## Phase 4 — Trace Replay (Differentiator)
+> Goal: re-run any past trace — the killer feature
+
+| Status | Task | Priority | Effort |
+|--------|------|----------|--------|
+| ✅ | Store full prompt + response per span in SQLite | High | 1 hr |
+| ✅ | `peekai replay <trace-id>` CLI command | High | 3 hrs |
+| ✅ | Replay with model swap (GPT-4o vs Claude) | High | 3 hrs |
+| ✅ | Replay with modified tool response | Medium | 4 hrs |
+| ✅ | Side by side original vs replayed trace in UI | Medium | 3 hrs |
+
+---
+
+## Phase 5 — Multi-Agent Support
+> Goal: visualize agent-to-agent calls
+
+| Status | Task | Priority | Effort |
+|--------|------|----------|--------|
+| ✅ | Parent/child span relationship in data model | High | 2 hrs |
+| ✅ | Agent handoff tracking via context propagation | High | 3 hrs |
+| ✅ | Multi-agent waterfall tree view in UI | High | 4 hrs |
+| ✅ | `peekai map <trace-id>` — ASCII agent flow in CLI | Medium | 2 hrs |
+
+---
+
+## Phase 6 — Polish + Ship v0.1
+> Goal: public release, real people using it
+
+| Status | Task | Priority | Effort |
+|--------|------|----------|--------|
+| ✅ | Write proper README with badges + demo gif | High | 2 hrs |
+| ⬜ | Record demo gif with a real agent example | High | 1 hr |
+| ✅ | Write `CONTRIBUTING.md` | Medium | 1 hr |
+| 🔵 | Publish to PyPI | High | 1 hr |
+| ⬜ | Post on HackerNews — Show HN | High | 30 min |
+| ⬜ | Post on Reddit r/LocalLLaMA + r/Python | High | 30 min |
+| ⬜ | Post demo gif on X/Twitter | High | 15 min |
+
+---
+
+## V2 Backlog — Do not touch until real users ask
+> Ideas for after v0.1 is live and people are using it
+
+- [ ] Eval hooks — attach pass/fail criteria to a trace
+- [ ] Failure clustering — group similar errors across runs automatically
+- [ ] Agent diff — compare two runs side by side
+- [ ] Export to Langfuse / OpenTelemetry format
+- [ ] VS Code extension
+- [ ] GitHub Action for CI agent testing
+- [ ] Async agent support improvements
+- [ ] Custom span types for domain-specific agents
+
+---
+
+## Weekly Routine
+
+```
+Sunday evening (15 min):
+  → Review Done column
+  → Pick next week tasks from Backlog
+  → Move to "This Week" on GitHub Projects
+
+Weekday evenings (1.5 hrs):
+  → 15 min: review board, pick one task
+  → 60 min: build only
+  → 15 min: commit, update board, note where you stopped
+
+Weekend (4-5 hrs/day):
+  → Bigger tasks, integrations, UI work
+```
+
+---
+
+*Last updated: April 2026*

peekai-0.1.0/CHANGELOG.md

@@ -0,0 +1,54 @@
+# Changelog
+
+All notable changes to PeekAI will be documented here.
+
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [0.1.0] — Unreleased
+
+First public release.
+
+### Added
+
+**Core**
+- `Trace` and `Span` dataclasses with full token, cost, and timing tracking
+- `Tracer` with `ContextVar`-based async/thread safety for nested span trees
+- SQLite storage at `~/.peekai/peekai.db` with WAL mode and indexed queries
+- Token cost table for OpenAI and Anthropic models with LiteLLM fallback
+
+**SDK patches** (auto-applied at `peekai.init()`)
+- OpenAI — sync + async `chat.completions.create`, including `stream=True`
+- Anthropic — sync + async `messages.create`, including `stream=True`
+- LiteLLM — sync + async `completion`
+
+**Decorators**
+- `@peekai.trace("name")` — wraps a function as a top-level trace
+- `@peekai.agent("name")` — wraps a sub-agent, LLM calls become children in the tree
+- `@peekai.tool("name")` — wraps a tool call as a TOOL span
+
+**CLI** (`peekai <command>`)
+- `list` — show recent traces with status, tokens, cost, duration
+- `view <id>` — full span waterfall with input/output/tool call detail
+- `map <id>` — ASCII agent flow tree with nested parent/child spans
+- `stats` — aggregate token + cost totals grouped by model
+- `replay <id>` — re-run a trace with optional `--model` and `--tool` overrides
+- `ui` — launch the Streamlit dashboard
+- `clear` — wipe all local storage
+
+**Web dashboard** (`peekai ui`)
+- Dashboard page — KPIs, cost over time, per-model breakdown
+- Traces page — filterable list with status, tokens, cost
+- Trace view — span waterfall with duration bars, I/O tabs, error highlighting
+- Replay page — side-by-side comparison with token/cost deltas
+
+**Trace replay**
+- Re-send stored prompts to any OpenAI-compatible or Anthropic model
+- Inject modified tool responses via `--tool name=value`
+- Replay saved as a new linked trace
+
+---
+
+[0.1.0]: https://github.com/peekai/peekai/releases/tag/v0.1.0

peekai-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,109 @@
+# Contributing to PeekAI
+
+Thanks for your interest in contributing. PeekAI is a small, focused tool — contributions that keep it simple and local-first are most welcome.
+
+---
+
+## Getting started
+
+```bash
+git clone https://github.com/peekai/peekai
+cd peekai
+uv sync --extra all
+uv run pytest tests/ -v
+```
+
+That's it. No Docker, no external services, no environment variables needed to run the tests.
+
+---
+
+## Project structure
+
+```
+src/peekai/
+├── __init__.py          # public API: init(), trace(), agent(), tool()
+├── core/
+│   ├── models.py        # Span, Trace dataclasses
+│   ├── tracer.py        # Tracer with ContextVar async safety
+│   ├── storage.py       # SQLite storage layer
+│   └── costs.py         # Token cost table per model
+├── patches/
+│   ├── openai_patch.py  # OpenAI SDK monkey-patch
+│   ├── anthropic_patch.py
+│   └── litellm_patch.py
+├── cli/
+│   ├── main.py          # Typer app + command registration
+│   ├── console.py       # Shared Rich console
+│   └── commands/        # One file per CLI command
+├── ui/
+│   ├── app.py           # Streamlit dashboard
+│   └── styles.py        # Inline HTML/CSS helpers
+└── replay/
+    └── engine.py        # Trace replay engine
+```
+
+---
+
+## How to contribute
+
+### Bug fixes
+Open an issue first if it's non-trivial. For small fixes, a PR is fine directly.
+
+### New features
+Open an issue to discuss before building. PeekAI is intentionally minimal — features that add cloud dependencies, require external services, or significantly increase complexity are unlikely to be merged into v0.x.
+
+### Adding a new SDK patch
+1. Create `src/peekai/patches/<sdk>_patch.py`
+2. Implement `patch(tracer)` and `unpatch()` following the existing pattern
+3. Register it in `src/peekai/__init__.py` inside `init()`
+4. Add a test in `tests/`
+
+### Adding a model to the cost table
+Edit `src/peekai/core/costs.py` — add the model name and `(input_per_1k, output_per_1k)` tuple. Include a source link in the PR description.
+
+---
+
+## Code style
+
+- **Formatter**: `ruff format` (line length 88)
+- **Linter**: `ruff check`
+- **Types**: mypy strict — all public functions need type annotations
+
+```bash
+uv run ruff check src/
+uv run ruff format src/
+uv run mypy src/peekai/
+```
+
+---
+
+## Tests
+
+All tests live in `tests/`. Run them with:
+
+```bash
+uv run pytest tests/ -v
+```
+
+- Tests use `tmp_path` fixtures for SQLite — no shared state between tests
+- No mocking of the OpenAI/Anthropic clients in unit tests — patches are tested via the tracer directly
+- New features should include at least one test
+
+---
+
+## Pull request checklist
+
+- [ ] Tests pass (`uv run pytest tests/ -v`)
+- [ ] No new ruff errors (`uv run ruff check src/`)
+- [ ] Type annotations on new public functions
+- [ ] BACKLOG.md updated if a tracked task is completed
+
+---
+
+## Reporting issues
+
+Include:
+- Python version (`python --version`)
+- PeekAI version (`peekai --version` or check `pyproject.toml`)
+- Minimal reproduction script
+- Full error traceback

peekai-0.1.0/LICENSE

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