Metadata-Version: 2.4
Name: hikaflow
Version: 2.1.2
Summary: Deterministic test replay and autonomous debugging with LLM-powered fix generation
Author-email: Hikaflow <hello@hikaflow.dev>
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://hikaflow.dev
Project-URL: Documentation, https://hikaflow.dev/docs
Keywords: debugging,testing,deterministic,replay,llm,autonomous
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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 :: Debuggers
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: typer>=0.12
Requires-Dist: click>=8.0
Requires-Dist: rich>=13.0
Requires-Dist: questionary>=2.0
Requires-Dist: httpx>=0.27
Requires-Dist: requests>=2.32.4
Requires-Dist: prompt_toolkit>=3.0
Requires-Dist: zstandard>=0.21
Requires-Dist: patch-ng>=1.18
Requires-Dist: watchfiles>=1.0
Requires-Dist: python-dotenv>=1.0
Requires-Dist: claude-agent-sdk>=0.1
Requires-Dist: langgraph>=0.2
Requires-Dist: langchain-core>=0.3
Requires-Dist: langchain-anthropic>=0.3
Provides-Extra: probe
Requires-Dist: psycopg2-binary>=2.9; extra == "probe"
Requires-Dist: redis>=4.5.4; extra == "probe"
Requires-Dist: aiohttp>=3.9.4; extra == "probe"
Requires-Dist: grpcio>=1.50; extra == "probe"
Requires-Dist: boto3>=1.28; extra == "probe"
Requires-Dist: pymongo>=4.0; extra == "probe"
Provides-Extra: llm
Requires-Dist: anthropic>=0.40; extra == "llm"
Requires-Dist: openai>=1.50; extra == "llm"
Requires-Dist: instructor>=1.0; extra == "llm"
Provides-Extra: interactive
Requires-Dist: ghapi>=1.0; extra == "interactive"
Requires-Dist: semgrep; extra == "interactive"
Provides-Extra: pydantic-ai-legacy
Requires-Dist: pydantic-ai!=1.30.0,>=1.30.1; extra == "pydantic-ai-legacy"
Requires-Dist: openai>=1.50; extra == "pydantic-ai-legacy"
Provides-Extra: recording
Requires-Dist: playwright>=1.40; extra == "recording"
Requires-Dist: zstandard>=0.22; extra == "recording"
Provides-Extra: api
Requires-Dist: fastapi>=0.109; extra == "api"
Requires-Dist: uvicorn>=0.22; extra == "api"
Requires-Dist: pyjwt>=2.8; extra == "api"
Requires-Dist: httpx>=0.27; extra == "api"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
Requires-Dist: pytest-timeout>=2.2; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: ruff>=0.1; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: fakeredis>=2.0; extra == "dev"
Requires-Dist: mongomock>=4.0; extra == "dev"
Requires-Dist: moto>=4.0; extra == "dev"
Requires-Dist: hypothesis>=6.92; extra == "dev"
Provides-Extra: observability
Requires-Dist: logfire>=0.40; extra == "observability"
Provides-Extra: otel
Requires-Dist: opentelemetry-sdk>=1.20.0; extra == "otel"
Requires-Dist: opentelemetry-exporter-otlp>=1.20.0; extra == "otel"
Requires-Dist: opentelemetry-instrumentation-asyncpg>=0.44b0; extra == "otel"
Requires-Dist: opentelemetry-instrumentation-aiohttp-client>=0.44b0; extra == "otel"
Requires-Dist: opentelemetry-instrumentation-redis>=0.44b0; extra == "otel"
Requires-Dist: opentelemetry-instrumentation-requests>=0.44b0; extra == "otel"
Requires-Dist: opentelemetry-instrumentation-httpx>=0.44b0; extra == "otel"
Requires-Dist: opentelemetry-instrumentation-sqlalchemy>=0.44b0; extra == "otel"
Provides-Extra: jobs
Requires-Dist: taskiq>=0.11; extra == "jobs"
Requires-Dist: taskiq-redis>=1.0; extra == "jobs"
Provides-Extra: retry
Requires-Dist: tenacity>=8.2; extra == "retry"
Provides-Extra: validation
Requires-Dist: libcst>=1.0; extra == "validation"
Requires-Dist: autopep8>=2.0; extra == "validation"
Requires-Dist: mypy>=1.0; extra == "validation"
Provides-Extra: transcript
Requires-Dist: fastjsonschema>=2.19; extra == "transcript"
Provides-Extra: analysis
Requires-Dist: mypy>=1.0; extra == "analysis"
Requires-Dist: ruff>=0.1; extra == "analysis"
Provides-Extra: dataflow
Requires-Dist: networkx>=3.0; extra == "dataflow"
Provides-Extra: learning
Requires-Dist: river>=0.21; extra == "learning"
Provides-Extra: impact
Requires-Dist: pytest-testmon>=2.1; extra == "impact"
Provides-Extra: integrations
Requires-Dist: slack-sdk>=3.27; extra == "integrations"
Requires-Dist: linear-api>=0.3; extra == "integrations"
Provides-Extra: optimization
Requires-Dist: dspy>=2.4; extra == "optimization"
Provides-Extra: mcp
Requires-Dist: fastmcp>=2.0; extra == "mcp"
Provides-Extra: all
Requires-Dist: autodebug[analysis,api,dataflow,dev,interactive,jobs,learning,llm,mcp,observability,optimization,otel,probe,retry,transcript,validation]; extra == "all"

# Hikaflow Debugger

**Deterministic test replay and autonomous debugging with LLM-powered fix generation.**

Hikaflow captures all external dependencies (HTTP, SQL, Redis, MongoDB, AWS, etc.) during test execution, enabling deterministic replay and automated fix generation.

## Features

- **Dependency Capture** - Records HTTP, SQL, Redis, MongoDB, gRPC, AWS S3 calls
- **Deterministic Replay** - Replay tests with exact same external responses
- **Flakiness Detection** - Identify non-deterministic tests automatically
- **Transcript Minimization** - Delta debugging to find minimal failing case
- **Autonomous Debugging** - LLM-powered fix generation with proof certificates
- **CI Integration** - GitHub Actions, GitLab CI, CircleCI support

## Installation

```bash
pip install autodebug

# With all optional dependencies
pip install autodebug[all]

# Or specific extras
pip install autodebug[probe]  # Full dependency capture
pip install autodebug[llm]    # LLM-powered debugging
```

## Quick Start

> **Note:** The legacy `autodebug` CLI is deprecated. Use `hikaflow` for all new workflows.

### 1. Authenticate

```bash
hikaflow login
```

### 2. Capture a failing test

```bash
# Run your test under Hikaflow instrumentation
hikaflow run -- pytest tests/test_api.py::test_user_creation -x

# Output:
# Run id: abc123
# Local bundle path: .autodebug/runs/abc123/
```

### 3. Debug interactively (requires LLM API key)

```bash
export ANTHROPIC_API_KEY=your_key  # or OPENAI_API_KEY

hikaflow debug
```

## CLI Commands

### Core Commands

| Command | Description |
|---------|-------------|
| `hikaflow setup` | Guided setup: doctor, login, init |
| `hikaflow login` | Authenticate via browser or device code |
| `hikaflow logout` | Clear stored credentials |
| `hikaflow whoami` | Show current authentication status |
| `hikaflow doctor` | Check environment and dependencies |
| `hikaflow status` | Show project status and recent errors |
| `hikaflow run` | Run a command under instrumentation |
| `hikaflow errors` | List recent production errors |
| `hikaflow inspect` | Inspect a specific error by ID |
| `hikaflow debug` | Interactive AI debugging session |
| `hikaflow watch` | Watch for new errors in real time |
| `hikaflow openclaw-eval` | Use OpenClaw to evaluate a run and suggest test/reliability improvements |

### `hikaflow replay` — Transcript replay & analysis

| Command | Description |
|---------|-------------|
| `replay diff` | Compare two transcripts |
| `replay export` | Export to HAR/curl/Postman |
| `replay minimize` | Delta-debug to smallest failing case |
| `replay debug` | Interactive transcript debugger |
| `replay share` | Share a run via public link |
| `replay repro` | Reproduce a run locally |
| `replay prod` | Replay a production error locally |
| `replay optimize` | Optimize a bundle for storage |
| `replay auto` | Autonomous debug workflow |
| `replay analyze` | Analyze a failure for root cause |

### `hikaflow flaky` — Flakiness detection & management

| Command | Description |
|---------|-------------|
| `flaky scan` | Scan for flaky tests and quarantine |
| `flaky detect` | Analyze tests for flakiness patterns |
| `flaky heal` | Automated healing for flaky tests |
| `flaky measure` | Run repeated tests to measure flakiness |

### Other command groups

| Group | Description |
|-------|-------------|
| `hikaflow patterns` | Manage the fix pattern database |
| `hikaflow session` | Session replay commands |
| `hikaflow issues` | Issue grouping commands |
| `hikaflow quarantine` | Manage test quarantine (list/add/remove/auto) |

## Supported Dependencies

### Full Support
- `requests` - HTTP client
- `httpx` - Async HTTP client
- `aiohttp` - Async HTTP client
- `psycopg2` / `psycopg` - PostgreSQL
- `redis` - Redis client
- `time` / `random` - Deterministic time and randomness

### Partial Support
- `sqlalchemy` - ORM (DBAPI layer captured)
- `grpcio` - gRPC (unary-unary only)
- `boto3` - AWS (S3 read operations only)
- `pymongo` - MongoDB (read operations only)

### Not Yet Supported
- `asyncpg` - Async PostgreSQL
- `aioredis` - Async Redis
- `motor` - Async MongoDB
- `celery` / `dramatiq` - Task queues

## How It Works

### 1. Capture Phase

When you run `hikaflow run -- pytest`, Hikaflow:
- Patches HTTP clients, database drivers, and other I/O
- Records all external calls with request/response data
- Captures timestamps, random values, and environment access
- Writes everything to `.autodebug/runs/<run_id>/`

### 2. Replay Phase

The repro harness:
- Rebuilds the exact Python environment
- Injects recorded responses instead of making real calls
- Blocks network access to ensure determinism
- Detects divergences from recorded behavior

### 3. Autonomous Debugging

With an LLM API key:
- Analyzes the failure and categorizes it
- Generates fix hypotheses using Claude or GPT
- Validates fixes by running them against the harness
- Produces proof certificates for working fixes

## Configuration

Create `.autodebug.yml` in your project root:

```yaml
# Environment handling
environment:
  tier: B  # A = pip freeze, B = lockfiles (poetry/pipenv)

# File capture
files:
  include:
    - "*.yaml"
    - "*.json"
    - "*.toml"
  exclude:
    - "*.pyc"
    - "__pycache__"
  max_size: 1048576  # 1MB

# Secret redaction
redaction:
  env_patterns:
    - "*_KEY"
    - "*_SECRET"
    - "*_TOKEN"
```

### Scan Confidence Guardrails

Environment flags for scan confidence and degraded-mode behavior:

- `HIKAFLOW_STRICT_EVIDENCE_MODE=1`  
  Demotes root-cause claims when evidence artifacts are missing.
- `HIKAFLOW_DEGRADED_SCAN_GUARD=1`  
  Marks root-cause conclusions as tentative when scan fidelity is degraded.

## CI Integration

### GitHub Actions

```yaml
- name: Run tests with Hikaflow
  uses: hikaflow-debug/hikaflow-debugger/.github/actions/capture@main
  with:
    test-command: pytest tests/ -x
    hikaflow-token: ${{ secrets.HIKAFLOW_TOKEN }}

- name: Comment on PR
  if: failure()
  uses: hikaflow-debug/hikaflow-debugger/.github/actions/pr-comment@main
```

### GitLab CI

```yaml
test:
  script:
    - pip install hikaflow
    - hikaflow run -- pytest tests/ -x
  artifacts:
    paths:
      - .autodebug/runs/
```

## Repo Hygiene

- Ignore TypeScript build artifacts: add `*.tsbuildinfo` to `.gitignore`.
- If a `.tsbuildinfo` file is already tracked, untrack it once:

```bash
git rm --cached web/tsconfig.tsbuildinfo
git commit -m "chore: stop tracking tsbuildinfo artifact"
```

## Project Structure

```
autodebug/              # CLI and core tools
  autonomous/           # LLM-powered debugging
  cli.py               # Command-line interface
  diff.py              # Transcript comparison
  minimize.py          # Delta debugging
  flakiness.py         # Flakiness detection

autodebug_probe/        # Capture instrumentation
  http_patch.py        # requests/httpx/aiohttp
  sql_patch.py         # psycopg2/psycopg
  redis_patch.py       # redis
  pymongo_patch.py     # pymongo
  boto3_patch.py       # boto3/botocore
  grpc_patch.py        # grpcio

autodebug_replay/       # Replay runtime
  http_replay.py       # HTTP replay
  sql_replay.py        # SQL replay
  redis_replay.py      # Redis replay

worker/                 # Background processing
  harness.py           # Repro harness generation
  validate.py          # Determinism validation
  optimize.py          # Storage optimization

api/                    # FastAPI server
  main.py              # API endpoints
  auth.py              # JWT authentication
```

## API Server

Deploy the API for team collaboration:

```bash
# Install API dependencies
pip install autodebug[api]

# Set environment variables
export SUPABASE_URL=...
export SUPABASE_SERVICE_ROLE_KEY=...
export CLERK_SECRET_KEY=...
export UPSTASH_REDIS_REST_URL=...
export UPSTASH_REDIS_REST_TOKEN=...

# Run the server
uvicorn api.main:app --host 0.0.0.0 --port 8000
```

## Development

```bash
# Clone and install
git clone https://github.com/hikaflow-debug/hikaflow-debugger.git
cd hikaflow-debugger
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Format code
black .
ruff check --fix .

# Type check
mypy autodebug/
```

## Requirements

- Python 3.9+
- Docker (for validation harness)
- LLM API key (for autonomous debugging)

## License

Proprietary - All rights reserved.

## Contributing

Contributions welcome! Please read the contributing guidelines first.

## Links

- [Documentation](https://hikaflow.com/docs)
- [Issues](https://github.com/hikaflow-debug/hikaflow-debugger/issues)
- [Changelog](CHANGELOG.md)
