Metadata-Version: 2.4
Name: nanoimports
Version: 0.1.0
Summary: AI-native runtime imports with automatic package resolution, installation, retry, lazy loading, and lightweight agent workflows.
Author: nanoimports contributors
License: MIT
Keywords: agentic,dependencies,imports,pip,runtime,uv
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.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# nanoimports

`nanoimports` is an autonomous, AI-native import layer for Python. It detects missing imports,
resolves the import name to the correct pip package, installs the dependency, retries the import,
and caches the resolution locally.

```python
from nanoimports import auto, smart_import

pd = smart_import("pandas")
cv2 = smart_import("cv2")
torch = smart_import("torch", lazy=True)

numpy = auto("numpy")
```

## What Works In The MVP

- `smart_import()` for import, install, retry, and local cache.
- `auto()` as a minimal ergonomic alias.
- Built-in import-to-package resolution for common mismatches:
  `cv2 -> opencv-python`, `PIL -> pillow`, `yaml -> pyyaml`, `sklearn -> scikit-learn`.
- SQLite cache for package resolutions and install logs.
- Installer selection with `uv pip install` preferred and `python -m pip install` fallback.
- `dry_run` mode.
- Lazy import proxy with first-attribute loading.
- Lightweight security checks before installation.
- Repair suggestions for DLL/native extension errors, version conflicts, and missing system deps.
- Conservative `sys.meta_path` hook used by `nanoimports run`.
- CLI for running scripts, resolving names, checking the environment, and managing cache.

## Install

From a checkout:

```bash
python -m pip install -e .
```

For development:

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

## API

```python
from nanoimports import smart_import

cv2 = smart_import("cv2")
```

When `cv2` is missing, nanoimports:

1. catches `ModuleNotFoundError`;
2. resolves `cv2` to `opencv-python`;
3. records the resolution in SQLite;
4. installs with `uv pip install opencv-python` or `python -m pip install opencv-python`;
5. invalidates import caches;
6. retries `import cv2`.

Use `dry_run=True` to inspect the planned install without changing the environment:

```python
smart_import("cv2", dry_run=True)
```

Use `install=False` to get standard import behavior plus nanoimports diagnostics:

```python
smart_import("pandas", install=False)
```

Use `lazy=True` for heavy dependencies:

```python
torch = smart_import("torch", lazy=True)
# torch is imported when an attribute is first accessed
```

## CLI

```bash
nanoimports run app.py
nanoimports doctor
nanoimports doctor --json
nanoimports resolve cv2
nanoimports cache list
nanoimports cache clear
nanoimports import cv2 --dry-run
```

`nanoimports run app.py` installs a conservative meta-path hook and then executes the script.
When Python cannot find a top-level module, the hook resolves and installs it before retrying.

## Architecture

The package is intentionally small and modular:

- `nanoimports.agents.detection.ImportDetectionAgent`
  normalizes `ImportError` and `ModuleNotFoundError`.
- `nanoimports.agents.resolution.PackageResolutionAgent`
  resolves import names to pip package names using cache, known mappings, fuzzy matching, and an
  optional LLM resolver protocol.
- `nanoimports.agents.environment.EnvironmentAgent`
  detects the active Python environment and runs `uv` or `pip`.
- `nanoimports.agents.security.SecurityAgent`
  blocks unsafe package-name syntax and warns about suspicious near-matches.
- `nanoimports.agents.repair.RepairAgent`
  suggests fixes for common post-install import failures.
- `nanoimports.runtime.lazy.LazyModule`
  defers expensive imports.
- `nanoimports.runtime.hooks.NanoImportHook`
  supports autonomous imports while running scripts.
- `nanoimports.cache.sqlite.ResolutionCache`
  stores resolutions and install logs.

## Cache

By default, cache data is stored at:

```text
~/.cache/nanoimports/nanoimports.sqlite3
```

Override this with:

```bash
NANOIMPORTS_CACHE_DIR=/path/to/cache nanoimports resolve cv2
```

or with CLI/API `cache_path`.

## Security Model

Runtime installation is powerful. nanoimports keeps the MVP deliberately conservative:

- package names must match a safe package-name pattern;
- known import aliases resolve through explicit mappings;
- suspicious near-matches produce warnings;
- `strict_security=True` turns warnings into hard failures;
- every install command is logged.

For production services, prefer pinned dependencies and use nanoimports in controlled workflows,
developer tools, notebooks, prototypes, or self-healing automation where runtime installation is
acceptable.

## Stretch Goals

The public API intentionally leaves room for:

- semantic imports such as `auto(task="vector database")`;
- richer PyPI metadata validation;
- notebook integration;
- VS Code extension support;
- dependency graph visualization;
- autonomous repair mode;
- telemetry dashboards.
