Metadata-Version: 2.4
Name: kraimind
Version: 0.2.0
Summary: AI-native dependency intelligence for developers — analyze, remove, migrate, clean
Project-URL: Homepage, https://github.com/kraimind/kraimind
Project-URL: Documentation, https://github.com/kraimind/kraimind#readme
Project-URL: Repository, https://github.com/kraimind/kraimind
Project-URL: Issues, https://github.com/kraimind/kraimind/issues
Author-email: Kraimind Contributors <hello@kraimind.dev>
License: MIT
License-File: LICENSE
Keywords: ai,cleanup,cli,dependencies,migrate,optimization,python,remove,supply-chain
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: click<8.3,>=8.0.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: packaging>=23.0
Requires-Dist: prompt-toolkit>=3.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: tomli>=2.0.0; python_version < '3.11'
Requires-Dist: typer>=0.9.0
Provides-Extra: ai
Requires-Dist: ollama>=0.1.0; extra == 'ai'
Requires-Dist: openai>=1.0.0; extra == 'ai'
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: build>=1.0.0; extra == 'dev'
Requires-Dist: isort>=5.0.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: respx>=0.20.0; extra == 'dev'
Requires-Dist: twine>=4.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# Kraimind

> **AI-native dependency intelligence for developers.**
> _Understand. Optimize. Trust._

Kraimind helps you audit, understand, and optimize your Python project's dependencies using rule-based intelligence, real CVE data, and optional AI insights.

```
Existing tools ask: "Is this package vulnerable?"
Kraimind asks:
  • Should I use this package?
  • Is there a better alternative?
  • Which dependencies are unused?
  • Which packages might be abandoned?
  • What CVEs affect this version?
```

---

## What Kraimind Does (v0.2.0)

| Feature | Description |
|---------|-------------|
| 🧹 **Unused dependency detection** | AST-scans your code, compares to declared deps, finds dead weight |
| 🛡️ **Trust scoring (0-100)** | Transparent, rule-based score from GitHub + PyPI + CVE signals |
| 🚨 **Real CVE scanning** | Live OSV.dev queries — actual vulnerabilities, not hand-curated lists |
| 💡 **Migration alternatives** | Curated database of better/modern replacements (e.g. `requests` → `httpx`) |
| ⚖️ **Side-by-side comparison** | `kraimind compare requests httpx` |
| 📦 **Lockfile support** | poetry.lock, Pipfile.lock, uv.lock for accurate analysis |
| ⚡ **Async parallel fetching** | 5-10x faster than sequential — 10 concurrent connections |
| 📊 **JSON output** | `--format json` for CI/CD pipelines |
| 🤖 **Optional AI insights** | OpenAI / Groq / Gemini / local Ollama — graceful fallback |
| 💾 **24h local cache** | Network-friendly, instant repeat runs |

---

## Installation

```bash
pip install kraimind
```

### With optional AI support

```bash
pip install "kraimind[ai]"
```

---

## Quick Start

```bash
# Verify installation
kraimind hello

# Analyze your project
kraimind analyze

# Inspect a specific package (with CVEs + alternatives)
kraimind explain requests

# Compare two packages side-by-side
kraimind compare requests httpx

# Full health report
kraimind doctor

# Cache management
kraimind cache info
kraimind cache clear
```

---

## Commands

### `kraimind analyze [PATH]`

Detects unused deps, fetches real CVE data, suggests migrations.

```bash
kraimind analyze                            # current dir
kraimind analyze ./my-project               # specific path
kraimind analyze --format json              # CI-friendly output
kraimind analyze --concurrency 20           # parallel API calls
kraimind analyze --no-ai                    # skip AI insights
```

### `kraimind explain <PACKAGE>`

Detailed package report — trust score, GitHub stats, CVEs, alternatives, AI insight.

```bash
kraimind explain requests
kraimind explain nose                  # shows ⛔ deprecated warning
kraimind explain tensorflow --no-ai
```

### `kraimind compare <PKG_A> <PKG_B>`

Side-by-side comparison: trust, stars, license, size, CVE counts.

```bash
kraimind compare requests httpx
kraimind compare flask fastapi
kraimind compare a b --format json
```

### `kraimind doctor [PATH]`

Aggregate health summary: total deps, unused count, average trust score, risk distribution.

```bash
kraimind doctor
kraimind doctor ./another-project --format json
```

### `kraimind cache <SUBCOMMAND>`

```bash
kraimind cache info          # show entries, size, location
kraimind cache clear         # delete all cached responses
kraimind cache clear --yes   # skip confirmation
```

### `kraimind share [PATH]`

Out of Claude Code credits mid-task? Bundle your codebase into a single link
any browsing-capable web AI can read — Claude.ai, ChatGPT (with browsing),
Gemini, Perplexity. Paste the URL, then keep iterating without re-explaining
the whole project.

```bash
kraimind share                   # → public URL, expires in 24h
kraimind share --full            # include lockfiles, larger bundle
kraimind share --file            # write kraimind-bundle.md locally instead
kraimind share --ttl 1           # link expires in 1 hour
```

Smart mode (default) packs the README, manifests, entry points, and the most
recently-modified source files into a ~150 KB markdown bundle that fits in any
AI's fetch limits.

**Always excluded:** `.env*` (except `.env.example`), `*.key`, `*.pem`,
`id_rsa*`, anything matching `*secret*`/`*credential*`, plus the usual
`.venv/`, `node_modules/`, build artifacts. Add a `.kraimindignore` (gitignore
syntax) to exclude more.

If the share endpoint is unreachable or rate-limited, the CLI auto-falls back
to writing the bundle locally so you always get *something*.

---

## Trust Score Algorithm

Every package gets a transparent, auditable 0-100 trust score:

| Signal | Impact |
|--------|--------|
| Stars > 10k | +15 |
| Stars 1k-10k | +15 |
| Stars 100-1k | +10 |
| Stars < 50 | -10 |
| Last commit < 90 days | +15 |
| Last commit < 365 days | +5 |
| Last commit > 365 days | -20 |
| Forks > 1k | +5 |
| Open issues < 50 | +5 |
| Open issues > 500 | -15 |
| Security policy enabled | +10 |
| Repository archived | -25 |
| Critical CVE | -25 |
| High-severity CVE | -15 |
| Medium-severity CVE | -8 |
| Low-severity CVE | -3 |
| 5+ CVEs | extra -5 |
| Published on PyPI | +5 |

### Score labels

| Score | Label |
|-------|-------|
| 90-100 | Excellent |
| 75-89 | Good |
| 60-74 | Acceptable |
| 40-59 | Caution |
| 0-39 | High Risk |

---

## Migration Alternatives

Kraimind ships with a curated alternatives database. Examples:

| Package | Suggestion | Effort |
|---------|------------|--------|
| `nose` | pytest | low |
| `requests` | httpx (sync + async) | low |
| `simplejson` | stdlib json or orjson | low |
| `mock` | stdlib unittest.mock | low |
| `tensorflow` | pytorch / jax | high |
| `marshmallow` | pydantic v2 | medium |
| `argparse` | typer / click | medium |

Run `kraimind explain <pkg>` to see full migration guidance.

---

## AI Insights (Optional)

Kraimind works great without any API key. AI is a progressive enhancement.

### Local AI (private, offline after setup)

```bash
ollama pull llama3.2
export KRAIMIND_LOCAL_AI=1
kraimind explain requests
```

### Cloud AI (any of these)

```bash
export OPENAI_API_KEY=sk-proj-...
export GROQ_API_KEY=gsk_...
export GEMINI_API_KEY=...
```

Kraimind tries them in order: local Ollama → OpenAI → Groq → Gemini → rule-based fallback.

---

## JSON Output (CI/CD)

```bash
kraimind analyze --format json | jq '.summary'
# {
#   "total_dependencies": 42,
#   "unused_count": 3,
#   "average_trust_score": 84.7
# }

kraimind doctor --format json | jq '.health.total_vulnerabilities'
# 0
```

Perfect for failing CI builds when CVE counts spike or trust drops.

---

## Caching

Kraimind caches GitHub, PyPI, and OSV.dev responses in `~/.kraimind/cache/`:
- 24h TTL for GitHub/PyPI
- 12h TTL for OSV (security data refreshes faster)
- Inspect via `kraimind cache info`
- Clear via `kraimind cache clear`

---

## Development

```bash
git clone https://github.com/kraimind/kraimind
cd kraimind

python -m venv .venv
.venv\Scripts\activate    # Windows
# source .venv/bin/activate   # macOS/Linux

pip install -e ".[ai,dev]"

pytest tests/ -v          # 84 tests
kraimind hello
kraimind analyze examples/sample-python-project
```

### Architecture

```
src/kraimind/
├── cli.py                 # Typer entrypoint (hello/analyze/explain/compare/doctor/cache)
├── async_clients.py       # asyncio.gather parallel API fetcher
├── github.py              # sync GitHub client + URL slug extractor
├── pypi.py                # sync PyPI client
├── vulnerability.py       # OSV.dev CVE scanner
├── alternatives.py        # curated migration database
├── trust.py               # 0-100 rule-based scorer
├── parser/
│   ├── requirements.py    # requirements.txt
│   ├── pyproject.py       # PEP 621 + Poetry
│   ├── package_json.py    # Node.js
│   ├── lockfile.py        # poetry.lock, Pipfile.lock, uv.lock
│   └── ast_scanner.py     # AST import scanner
├── ai/
│   ├── explainer.py       # provider orchestrator
│   ├── local_llm.py       # Ollama
│   └── cloud_llm.py       # OpenAI / Groq / Gemini
└── utils/
    ├── cache.py           # filesystem cache
    ├── formatting.py      # Rich panels, tables, score bars
    └── mappings.py        # import → package canonical names
```

---

## License

MIT — see [LICENSE](LICENSE).
