sydes 0.1.0

System intelligence for backend systems, starting with incident analysis from logs.

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

pip install sydes

📦 Build and Release

Build release artifacts locally:

python -m build

Upload them to PyPI:

twine upload dist/*

Verify the published package:

pip install sydes
sydes --help
sydes incident analyze --help

---

⚙️ Quickstart Setup

Before running incident analysis, choose one model path:

OpenAI

export OPENAI_API_KEY=your_openai_api_key

Then run with:

--model openai:gpt-4.1-mini

Ollama

Start Ollama and pull a local model:

ollama serve
ollama pull llama3.1

Then run with:

--model ollama:llama3.1

Optional environment variables:

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

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

sydes incident analyze [OPTIONS] <log files>

Example

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)

sydes incident analyze logs/*.log

→ broad, approximate understanding

---

2. Grep (precise signal)

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

→ exact failure analysis

---

3. Query (semantic focus)

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

→ AI-driven reasoning

---

4. Query + Grep (recommended)

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

→ best results (focused + precise)

---

⚙️ Model Support

Example:

--model openai:gpt-4.1-mini

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

---

🧩 Example Logs

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.