Metadata-Version: 2.4
Name: causalityos
Version: 0.10.0
Summary: AI-powered root cause analysis and autonomous debugging for software projects
Author-email: CausalityOS Contributors <causalityos@proton.me>
License-Expression: MIT
Project-URL: Homepage, https://github.com/causalityos/causalityos
Project-URL: Bug Tracker, https://github.com/causalityos/causalityos/issues
Project-URL: Source Code, https://github.com/causalityos/causalityos
Keywords: debugging,root-cause-analysis,developer-tools,git,testing,ai,cli,autonomous,code-intelligence
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.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Debuggers
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Version Control :: Git
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.9.0
Requires-Dist: rich>=13.0.0
Provides-Extra: test
Requires-Dist: pytest>=7.0.0; extra == "test"
Provides-Extra: dev
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: twine>=4.0.0; extra == "dev"
Dynamic: license-file

# CausalityOS

CausalityOS is a terminal-first developer tool for investigating why software
projects behave differently after code, test, log, or Git history changes.

Current release: `0.10.0`

## Installation

After publication to PyPI:

```bash
python -m pip install causalityos
```

For local development from this repository:

```bash
python -m pip install -e ".[dev]"
```

## First Commands

```bash
causality --help
causality --version
causality analyze .
```

The PyPI distribution is named `causalityos`. The Python import package and CLI
module remain named `causality`:

```python
import causality

print(causality.__version__)
```

## CLI Overview

```bash
causality analyze .
causality investigate .
causality reason .
causality verify . --dry-run
causality causal . --json
causality diagnose .
causality fix .
causality llm status
```

Core command groups:

- `analyze`: project structure, language counts, Git summary, code summary, and test discovery.
- `git`: recent commits, commit details, file history, hotspots, and repository stats.
- `code`: Python AST summaries, dependency graph, and impact analysis.
- `tests`: pytest discovery, test execution, and test history.
- `logs`: log level counting and error pattern fingerprinting.
- `investigate`: multi-layer evidence collection.
- `reason`: deterministic, evidence-grounded root-cause hypotheses.
- `verify`: isolated Git worktree counterfactual verification.
- `causal`: multi-evidence causal correlation.
- `diagnose`: end-to-end autonomous diagnosis.
- `fix`: autonomous repair proposal and isolated repair experiment.
- `llm`: local LLM provider status.

## Configuration

CausalityOS has no required API keys. The optional local LLM explanation layer
uses Ollama through Python standard-library HTTP calls.

Optional environment variables:

- `CAUSALITY_LLM_PROVIDER`: `ollama` by default, or `mock` for tests.
- `CAUSALITY_LLM_HOST`: defaults to `http://localhost:11434`.
- `CAUSALITY_LLM_MODEL`: defaults to `qwen2.5:3b`.
- `CAUSALITY_LLM_TIMEOUT`: request timeout in seconds.

To use local LLM explanations, install Ollama separately and pull the configured
model:

```bash
ollama pull qwen2.5:3b
causality llm status
```

Deterministic analysis works without Ollama.

## Runtime Requirements

- Python 3.11 or newer
- Runtime Python packages: `typer`, `rich`
- External command-line tools for selected features:
  - `git` for Git intelligence and counterfactual worktrees
  - `pytest` in the analyzed project environment when running `causality tests run`, `verify`, `diagnose`, or `fix`

Development extras are separate from runtime dependencies:

```bash
python -m pip install -e ".[test]"
python -m pip install -e ".[dev]"
```

## Release Build

Build local distributions:

```bash
python -m build
```

Install a generated wheel into a clean environment:

```bash
python -m pip install dist/causalityos-0.10.0-py3-none-any.whl
```

## Safety Model

CausalityOS avoids modifying the user's main working tree during analysis and
verification. Counterfactual experiments use isolated Git worktrees or temporary
directories. The `fix` command runs in safe mode by default and only applies a
verified repair when `--apply` is explicitly passed.

## Supported Platforms

CausalityOS is intended to run on Windows, macOS, and Linux with Python 3.11+.
The code uses `pathlib` and platform-independent subprocess APIs.

## Limitations

- Python code intelligence is currently AST-based static analysis.
- Runtime test intelligence uses pytest.
- Git-dependent commands require a Git executable on `PATH`.
- LLM explanations require a separately installed local Ollama service.

## License

license = "MIT"

