Metadata-Version: 2.4
Name: folio-kit
Version: 0.1.5
Summary: Portable, AI-native data sheets.
Project-URL: Homepage, https://github.com/nyuta01/folio
Project-URL: Documentation, https://github.com/nyuta01/folio/blob/main/docs/design-docs/overview.md
Author: Folio contributors
License: MIT
Keywords: ai-agent,data-contract,duckdb,jsonl,odcs
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.13
Requires-Dist: anthropic>=0.40
Requires-Dist: duckdb>=1.0
Requires-Dist: fastapi>=0.110
Requires-Dist: fastmcp>=2.6
Requires-Dist: filelock>=3.13
Requires-Dist: httpx>=0.27
Requires-Dist: platformdirs>=4.2
Requires-Dist: pydantic>=2.6
Requires-Dist: pyyaml>=6.0
Requires-Dist: rfc8785>=0.1.4
Requires-Dist: typer>=0.12
Requires-Dist: uvicorn[standard]>=0.27
Description-Content-Type: text/markdown

# folio-kit

Portable, AI-native data sheets. The Python distribution ships three
console scripts and a Python SDK for reading and writing typed data
sheets that humans and AI agents can both edit.

```
my-sheet/
├── contract.yaml         # required — ODCS subset
├── records.jsonl         # required — one JSON object per line
├── derivations/          # optional — derivation files (ai / python / sql / cross_sheet / import / http)
├── scripts/              # optional — reusable Python scripts
├── provenance.jsonl      # append-only audit log
└── README.md             # optional, with typed frontmatter
```

## What you get

| Surface | Command | Purpose |
|---|---|---|
| CLI | `folio` | validate, query, list, upsert, delete, materialize, status, provenance, serve, script, export |
| MCP server | `folio-mcp` | FastMCP server exposing the SDK over stdio or HTTP — drop into Claude Desktop / Cursor / any MCP client |
| Viewer backend | `folio-viewer` | Local-only FastAPI server that powers the Folio Viewer desktop app and web UI |
| Python SDK | `from folio import open_sheet` | Programmatic access to the same operations as the CLI |

## Install

```bash
pipx install folio-kit
# or
uv tool install folio-kit
```

The distribution name is `folio-kit`; the on-disk command is `folio`.

## Quickstart

```bash
folio validate ./my-sheet
folio materialize ./my-sheet --actor agent:demo
folio query ./my-sheet "SELECT id, status FROM records LIMIT 5"
```

Programmatic:

```python
from folio import open_sheet

sheet = open_sheet("./my-sheet", actor="agent:demo")
sheet.upsert({"id": "cust_001", "company_name": "Acme", "country": "Japan"})
result = sheet.materialize()
print(result)   # {"materialized": 1, "skipped": 0, "failures": [], "total_cost": 0.0}
```

## Derivations

A `derivations/<field>.yaml` declares how a derived column is filled.
Folio ships six kinds:

- `ai` — call an LLM (Anthropic by default; injectable AIClient)
- `python` — run a reusable script from `scripts/`
- `sql` — DuckDB query against the sheet's records view
- `cross_sheet` — pull a value from a sibling Folio sheet (1:1 by PK)
- `import` — copy from a CSV / JSON file
- `http` — fetch from a URL

Every value comes with a provenance entry (actor, timestamp, input
hash, model + cost for `ai`). Re-runs are content-hashed and cached.

## Requirements

- Python 3.13+
- Optional: `ANTHROPIC_API_KEY` in the environment if you use `kind: ai`
  derivations against the default adapter. Bring-your-own `AIClient`
  for any other provider.

## Links

- **Source & full documentation:** https://github.com/nyuta01/folio
- **Specification:** [SPECIFICATION.md](https://github.com/nyuta01/folio/blob/main/SPECIFICATION.md) — the complete contract, formats, and semantics
- **Examples:** four working sheets under
  [`examples/`](https://github.com/nyuta01/folio/tree/main/examples/)
  (customers, research-notes, research-memory, onboarding)
- **Agent skills:** the
  [`folio-agent-skills`](https://www.npmjs.com/package/folio-agent-skills)
  npm package ships ready-to-install SKILL.md files for Claude / Cursor /
  any skills.sh-compatible agent runtime.
- **Issues & roadmap:** https://github.com/nyuta01/folio/issues

## License

MIT.
