Metadata-Version: 2.4
Name: causalog
Version: 1.0.2
Summary: Intelligent Log Root Cause Analysis — one command opens a full React dashboard.
Author-email: CausaLog Team <hello@causalog.dev>
License: MIT License
        
        Copyright (c) 2025 CausaLog Team
        
        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.
        
Project-URL: Homepage, https://github.com/your-org/causalog
Project-URL: Source, https://github.com/your-org/causalog
Project-URL: Bug Tracker, https://github.com/your-org/causalog/issues
Project-URL: Documentation, https://github.com/your-org/causalog#readme
Keywords: log,rca,root-cause,anomaly,observability,dashboard,devops
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Topic :: System :: Logging
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Debuggers
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: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Environment :: Web Environment
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.109.0
Requires-Dist: uvicorn[standard]>=0.27.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: scikit-learn>=1.3.0
Requires-Dist: spacy>=3.7.0
Requires-Dist: python-multipart>=0.0.9
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: httpx>=0.26; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Requires-Dist: ruff>=0.3; extra == "dev"
Dynamic: license-file

# CausaLog 🔍

> Intelligent Log Root Cause Analysis — one command, instant dashboard.

## Quick start

```bash
pip install causalog
python -m spacy download en_core_web_sm

causalog run                     # auto-discovers .log/.json in current directory
causalog run /var/log/app.log    # explicit file
causalog run logs/               # scan a directory
```

Opens an interactive React dashboard at **http://localhost:8000** showing:

- **Dashboard** — metric cards, system health timeline, AI insights, root cause hypotheses
- **Analysis** — full paginated log stream with filtering by level/service/keyword
- **Clusters** — grouped log clusters with severity, keywords, sparklines
- **Timelines** — area chart of errors/anomalies over time with spike markers and debug runbooks

## Options

```
causalog run app.log --port 9000       # custom port
causalog run app.log --no-browser      # server only, no browser popup
causalog run app.log --no-server       # terminal report only
causalog run app.log --report out.json # also save a JSON report
causalog version
```

## Windows install troubleshooting

If editable install fails with:

`[WinError 32] ... python...\Scripts\causalog.exe is being used by another process`

it means a running `causalog` process is locking the executable. Stop it first, then reinstall:

```powershell
Get-CimInstance Win32_Process |
  Where-Object { $_.ExecutablePath -like "*\\Python314\\Scripts\\causalog.exe" } |
  ForEach-Object { Stop-Process -Id $_.ProcessId -Force }

python -m pip install -e .
```

Tip: always use `python -m pip ...` to ensure you are installing into the same Python interpreter.

## How it works

```
Log file upload
      ↓
Preprocessing    (Pandas + Regex) — parse timestamps, levels, services
      ↓
NLP Extraction   (spaCy)          — extract keywords from messages
      ↓
Clustering       (TF-IDF+KMeans)  — group similar log entries
      ↓
Anomaly Detection(IsolationForest)— flag statistically unusual entries
      ↓
Ontology Mapping (keyword→cause)  — map to root cause categories
      ↓
RCA Engine       (rule-based)     — frequency + per-error details
      ↓
Intelligence Layer               — hypotheses, confidence scores,
                                   temporal trend analysis,
                                   actionable debug suggestions
      ↓
React Dashboard  (FastAPI + CDN)  — live, connected, no npm needed
```

## Requirements

- Python ≥ 3.9
- spaCy English model: `python -m spacy download en_core_web_sm`

## Stack

| Layer          | Technology                       |
|----------------|----------------------------------|
| Backend API    | FastAPI + Uvicorn                |
| Frontend       | React 18 + Recharts (CDN, no npm)|
| ML/NLP         | scikit-learn, spaCy              |
| Data           | Pandas, NumPy                    |

## License

MIT
