Metadata-Version: 2.4
Name: sydes
Version: 0.1.0
Summary: System intelligence for backend systems, starting with incident analysis from logs.
Author-email: karims <karimullasaheb@gmail.com>
Keywords: cli,incident-analysis,logs,observability,root-cause
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: Utilities
Requires-Python: >=3.12
Requires-Dist: typer>=0.12.0
Description-Content-Type: text/markdown

# Sydes — Incident Analysis

Understand production incidents from logs using AI.

Stop reading thousands of log lines manually.
Get a structured root-cause hypothesis, timeline, and evidence in seconds.

---

## 📦 Installation

```bash
pip install sydes
```

## 📦 Build and Release

Build release artifacts locally:

```bash
python -m build
```

Upload them to PyPI:

```bash
twine upload dist/*
```

Verify the published package:

```bash
pip install sydes
sydes --help
sydes incident analyze --help
```

---

## ⚙️ Quickstart Setup

Before running incident analysis, choose one model path:

### OpenAI

```bash
export OPENAI_API_KEY=your_openai_api_key
```

Then run with:

```bash
--model openai:gpt-4.1-mini
```

### Ollama

Start Ollama and pull a local model:

```bash
ollama serve
ollama pull llama3.1
```

Then run with:

```bash
--model ollama:llama3.1
```

Optional environment variables:

```bash
export OLLAMA_BASE_URL=http://127.0.0.1:11434
export AIAUTOPSY_OLLAMA_MODEL=llama3.1
export AIAUTOPSY_MODEL_TIMEOUT=60
```

Use `--require-model` if the command should fail instead of continuing when the requested model backend is unavailable.

---

## ⚡ Quick Demo

```bash
sydes incident analyze \
  --model openai:gpt-4.1-mini \
  --require-model \
  --query "Why is checkout returning 503 errors?" \
  logs/incident.log
```

```

== INCIDENT SUMMARY ==
API Gateway timeouts to db-proxy causing 503 errors on checkout requests

== INCIDENT WINDOW ==
Mode: exact
Start: 2026-03-25T13:34:05+00:00
End: 2026-03-25T13:34:05+00:00
Timeline events: 1

== TOP HYPOTHESIS ==
API Gateway timeouts to db-proxy causing 503 errors on checkout requests
The API Gateway service is experiencing repeated HTTP 503 errors for checkout endpoints, all linked to upstream db-proxy timeouts. This explains early high-severity error signals and cross-host impact within the API Gateway service, and correlates with observed degraded operations and dependency failures.
Source: openai:gpt-4.1-mini

== CONFIDENCE / STRENGTH ==
Strength: 0.85

== WHY THIS HYPOTHESIS ==
- Primary cause: API Gateway timeouts to db-proxy causing 503 errors on checkout requests
- Observed evidence: At 2026-03-25T13:34:05, api-gateway host=api-2 logged ERROR level HTTP 503 responses on /v1/checkout due to upstream=db-proxy timeout | Repeated ERROR level 503 responses on /v1/checkout from api-gateway hosts (api-1 and api-2) within 30 seconds, all citing upstream=db-proxy err=timeout
- Contributing signals: The upstream db-proxy timeout from api-gateway triggers HTTP 503 errors returned to clients
- Uncertainty: No direct error or exception logs from db-proxy confirm root cause beyond timeouts reported by api-gateway

== ALTERNATIVES CONSIDERED ==
- Likely api show timeouts causing service 503 errors (Assessment Strength: 0.60)
- Transient network latency or connectivity issues between api-gateway and db-proxy causing timeouts (Assessment Strength: 0.55)

== AFFECTED SERVICES ==
api, api-gateway

== KEY SIGNALS ==
- 1 timeline events from 2026-03-25T13:34:05+00:00 to 2026-03-25T13:34:05+00:00, with 0 burst(s).
- 1 cluster(s); largest cluster cluster-000006 contains 2 event(s).

== EVIDENCE SUMMARY ==
Files: 1 | Lines: 4096 | Timestamp candidates: 205
Parsed timestamps: 205 | Sequence-only records: 0
Ingestion timestamp hints: 4096 | Seed records: 12 | Evidence refs: 12
Seed filters: query=Why is checkout returning 503 errors?, query_refined=why is gateway host

== NEXT STEPS ==
- Validate the top hypothesis against recent deploys and dependency changes.

== MODEL USED ==
Requested: openai:gpt-4.1-mini
Resolved reasoning model: gpt-4.1-mini
Interpretation backend: local-small
Reasoning backend: openai:gpt-4.1-mini
```

---

## 🧠 What Sydes does

Sydes analyzes raw logs and automatically:

- extracts structured events
- groups related signals
- builds a timeline of the incident
- generates root-cause hypotheses
- shows supporting evidence

---

## 🚀 Usage

```bash
sydes incident analyze [OPTIONS] <log files>
```

### Example

```bash
sydes incident analyze logs/*.log \
  --query "Why are session lookups failing?"
```

---

## 🔍 Modes of Analysis

Sydes works best when you guide it.

### 1. Whole log (overview)

```bash
sydes incident analyze logs/*.log
```

→ broad, approximate understanding

---

### 2. Grep (precise signal)

```bash
sydes incident analyze logs/*.log \
  --grep "cache_unavailable"
```

→ exact failure analysis

---

### 3. Query (semantic focus)

```bash
sydes incident analyze logs/*.log \
  --query "Why are session lookups failing?"
```

→ AI-driven reasoning

---

### 4. Query + Grep (recommended)

```bash
sydes incident analyze logs/*.log \
  --query "Why are session lookups failing?" \
  --grep "session lookup failed"
```

→ best results (focused + precise)

---

## ⚙️ Model Support

Example:

```bash
--model openai:gpt-4.1-mini
```

Use `--require-model` to fail if the model is unavailable instead of falling back.

---

## 🧩 Example Logs

```bash
sydes incident analyze examples/auth_cache_failure.log \
  --query "Why are session lookups failing?"
```

---

## 🚧 Status

This is an early version of Sydes.

- AI reasoning may be imperfect
- best results come from focused queries
- designed for real-world logs, not toy datasets

---

## 🔮 Roadmap

Sydes is evolving into a broader system intelligence platform:

- incident analysis (current)
- system understanding from code
- integration test generation
- system graph + reasoning

---

## 🧠 Philosophy

Logs are not the problem.

The problem is:
- too much data
- no structure
- no reasoning layer

Sydes adds:
- structure (events, clusters, timeline)
- reasoning (hypotheses grounded in evidence)

---

## 🤝 Contributing

PRs and feedback welcome.
