Metadata-Version: 2.4
Name: minkatec-fractal
Version: 0.3.0
Summary: A local-first code intelligence platform
License: MIT
Keywords: ast,cli,code-intelligence,knowledge-graph
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
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
Requires-Python: >=3.11
Requires-Dist: anthropic>=0.40.0
Requires-Dist: duckdb>=1.1.0
Requires-Dist: fastapi>=0.111.0
Requires-Dist: gitpython>=3.1.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: numpy>=1.26.0
Requires-Dist: pathspec>=0.12.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: sentence-transformers>=3.0.0
Requires-Dist: sse-starlette>=2.1.0
Requires-Dist: tree-sitter-go>=0.23.0
Requires-Dist: tree-sitter-javascript>=0.23.0
Requires-Dist: tree-sitter-python>=0.23.0
Requires-Dist: tree-sitter-typescript>=0.23.0
Requires-Dist: tree-sitter-yaml>=0.7.2
Requires-Dist: tree-sitter>=0.23.0
Requires-Dist: typer>=0.12.0
Requires-Dist: uvicorn>=0.30.0
Provides-Extra: dev
Requires-Dist: mypy>=1.11.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.6.0; extra == 'dev'
Requires-Dist: types-tqdm; extra == 'dev'
Description-Content-Type: text/markdown

# Fractal

A local-first code intelligence platform that transforms source repositories into a navigable, queryable knowledge store for humans and AI agents.

- **Offline-first** — no cloud required; LLM is optional
- **Incremental** — only reprocesses changed files
- **Multi-language** — Python, TypeScript, JavaScript, Dart/Flutter, and infrastructure files (extensible via plugins)
- **Graph-backed** — relationships, dependencies, call chains stored in DuckDB

---

## Install

```bash
# via uv (recommended)
uv tool install fractal

# via pip
pip install fractal

# development
uv pip install -e .
```

---

## Quick Start

```bash
cd my-project

fractal init          # create .fractal/ workspace
fractal ingest        # index everything: files, symbols, relationships, embeddings
fractal ask technical "authentication"
```

---

## Workflow

### 1 — Initialize

```bash
fractal init [PATH]
```

Creates `.fractal/` inside the repository with:

```
.fractal/
├── config.yaml      # editable configuration
├── knowledge.db     # DuckDB knowledge store
├── snapshots/
├── cache/
└── logs/
```

Use `--force` to reinitialize an existing workspace.

---

### 2 — Configuration

Edit `.fractal/config.yaml` (auto-generated on `init`). Full template at [`config.yaml.example`](config.yaml.example).

```yaml
llm:
  provider: anthropic # anthropic | none
  model: claude-sonnet-4-6
  # api_key: sk-ant-...        # or set ANTHROPIC_API_KEY

embedding:
  provider: local # local (sentence-transformers) | none
  model: all-MiniLM-L6-v2
  device: cpu # cpu | cuda

analysis:
  languages:
    [
      python,
      typescript,
      javascript,
      dart,
      dockerfile,
      docker-compose,
      serverless,
      kubernetes,
      github-actions
    ]
  max_file_size_bytes: 1048576
  exclude_patterns:
    - node_modules/**
    - .git/**
    - dist/**
    - .venv/**
```

---

### 3 — Ingest

```bash
fractal ingest [PATH]           # full index
fractal ingest --verbose        # show detailed progress
```

Pipeline: scan → fingerprint → snapshot → parse symbols → extract relationships → generate embeddings.

Fractal auto-detects file language by extension, filename, or content. No manual configuration needed for standard project layouts.

---

### 4 — Incremental Update

After modifying files, only reprocess what changed:

```bash
fractal update                  # diff against last snapshot
fractal update --since HEAD~5   # scope to files changed in last 5 commits
fractal update --verbose
```

---

## Querying

### Technical (no LLM required)

```bash
fractal ask technical "UserRepository"
fractal ask technical "authentication" --depth 2
fractal ask technical "config" --depth 1 --evidence
```

### Semantic (requires LLM)

```bash
fractal ask semantic "How does authentication work?"
fractal ask semantic "What handles billing?" --depth 3 --evidence
```

### Hybrid

```bash
fractal ask hybrid "How is a user created?" --depth 2
```

`--depth N` controls traversal scope: `0` = direct match, `1` = immediate deps, `2` = transitive, `3` = architectural context, `4+` = exhaustive.

`--evidence` appends the files, symbols, and relationships consulted.

---

## Symbol & Graph Navigation

```bash
fractal symbol UserService                  # exact lookup by name
fractal symbol create --kind function       # filter by kind
fractal symbol User --file src/models.py    # scope to file

fractal deps UserRepository                 # direct + reverse dependencies
fractal trace createUser                    # full call chain (callers + callees)
fractal impact UserService                  # modification risk + fan-in
fractal explore AuthController              # one-hop expansion all directions
```

---

## Architectural Discovery

```bash
fractal architecture    # modules, domains, dependency boundaries
fractal concepts        # inferred semantic concepts (auth, billing, …)
```

Concepts are pre-extracted during `ingest` — no LLM needed at query time.

---

## AI Agent Support

```bash
fractal context "Add MFA to authentication"     # ranked files, modules, deps, risks
fractal context "Refactor payment service" --format json

fractal investigate "Remove legacy API"         # impact + risk assessment
```

---

## Maintenance

```bash
fractal refresh         # rebuild embeddings + summaries, preserve source indexes
fractal clean           # remove embeddings + cache only
fractal clean --all     # remove entire .fractal/ workspace
```

---

## Graph Dashboard

Fractal ships a zero-config local web UI — no Node.js, no build step, all assets bundled offline.

```bash
fractal serve .                # launch at http://127.0.0.1:8080
fractal serve . --port 9000    # custom port
fractal serve . --open         # open browser automatically
```

**Features:**

| Tab | What it does |
|-----|-------------|
| **Symbols** | Searchable, filterable symbol list with detail panel (kind, file, line range, signature, docstring) |
| **Graph** | Interactive vis-network graph — click any node to expand its relationships; depth slider 1–4; edge legend |
| **Commands** | Run any `fractal` CLI command from the browser; output streams live via SSE; Cancel button |
| **Architecture** | Streams `fractal architecture` output as a structured report |
| **Concepts** | Streams `fractal concepts` output as expandable cluster list |

After `fractal ingest` / `fractal update` completes in the Commands panel, the symbol list and workspace stats refresh automatically.

An empty workspace (no data ingested yet) shows a clear banner: _"No workspace data. Run: fractal ingest ."_

---

## All Commands

| Command                | Description                      |
| ---------------------- | -------------------------------- |
| `init`                 | Initialize workspace             |
| `ingest`               | Full repository index            |
| `update [--since REF]` | Incremental update               |
| `serve [--port N]`     | Launch Graph Dashboard web UI    |
| `ask semantic QUERY`   | LLM-backed conceptual answer     |
| `ask technical QUERY`  | Symbol/graph lookup, no LLM      |
| `ask hybrid QUERY`     | Combined                         |
| `symbol NAME`          | Look up symbol by name/file/kind |
| `deps SYMBOL`          | Dependency graph                 |
| `trace FUNCTION`       | Execution chain                  |
| `impact SYMBOL`        | Modification risk                |
| `explore ENTITY`       | Relationship expansion           |
| `architecture`         | High-level structure             |
| `concepts`             | Semantic concept list            |
| `context TASK`         | AI agent context package         |
| `investigate CHANGE`   | Impact assessment                |
| `refresh`              | Rebuild derived knowledge        |
| `clean [--all]`        | Remove artifacts                 |

Full flag reference: [`docs/cli-reference.md`](docs/cli-reference.md)
Configuration reference: [`docs/config-reference.md`](docs/config-reference.md)
Plugin guide: [`docs/plugin-guide.md`](docs/plugin-guide.md)

---

## How It Works

```
fractal init
  └─ creates .fractal/config.yaml + knowledge.db, runs SQL migrations

fractal ingest
  ├─ scan      — walk repo, detect languages, respect .gitignore
  ├─ fingerprint — SHA-256 + mtime per file
  ├─ snapshot  — point-in-time file inventory in DuckDB
  ├─ parse     — tree-sitter ASTs (Python/TS/JS) + regex (Dart) + YAML (infra) → symbols
  ├─ relate    — IMPORTS / CALLS / EXTENDS / BELONGS_TO relationships
  ├─ embed     — sentence-transformers vectors stored in DuckDB
  └─ enrich    — heuristic concept detection (LLM-backed when configured)

fractal update
  ├─ diff      — current fingerprints vs last snapshot
  ├─ reconcile — remove stale symbols, relationships, embeddings
  ├─ reprocess — only changed/added files
  └─ snapshot  — new snapshot recorded

fractal ask technical "X"
  ├─ symbol search — DuckDB ILIKE on name
  ├─ file search   — path ILIKE
  └─ graph expand  — BFS/DFS up to --depth hops

fractal serve .
  ├─ FastAPI        — REST API over .fractal/knowledge.db
  ├─ SSE streaming  — live command output via EventSource
  └─ static UI      — bundled HTML/JS/CSS (vis-network + Alpine.js, no CDN)
```

---

## Language & File Support

### Source languages (full symbol extraction)

| Language       | Extensions                    | Symbols extracted                                                                       |
| -------------- | ----------------------------- | --------------------------------------------------------------------------------------- |
| Python         | `.py`                         | classes, functions, methods, imports                                                    |
| TypeScript     | `.ts`, `.tsx`                 | classes, functions, interfaces, imports                                                 |
| JavaScript     | `.js`, `.jsx`, `.mjs`, `.cjs` | classes, functions, imports                                                             |
| Dart / Flutter | `.dart`                       | classes, mixins, enums, extensions, typedefs, imports; Flutter widget kinds auto-tagged |

### Infrastructure & config files (resource extraction)

Detection is automatic — no configuration needed. Fractal uses filename, path, and content sniffing.

| Format               | Detected by                                             | Symbols extracted                                      |
| -------------------- | ------------------------------------------------------- | ------------------------------------------------------ |
| Dockerfile           | `Dockerfile*`, `*.dockerfile`                           | build stages, exposed ports, ENV vars, ARGs            |
| docker-compose       | `docker-compose*.yml`, `compose.yml`, content heuristic | services, volumes, networks                            |
| Serverless Framework | `serverless.yml/yaml`                                   | functions (handler + events), CloudFormation resources |
| Kubernetes           | `apiVersion:` in YAML content                           | resources by kind/name/namespace, containers           |
| GitHub Actions       | `.github/workflows/*.yml`                               | workflows, jobs                                        |

### Extensible via plugins

Add any language or format without modifying core — see [`docs/plugin-guide.md`](docs/plugin-guide.md).

---

## Requirements

- Python 3.11+
- [uv](https://docs.astral.sh/uv/) (recommended) or pip

Optional:

- `ANTHROPIC_API_KEY` for semantic queries
- CUDA device for faster embeddings (`device: cuda` in config)
