Metadata-Version: 2.4
Name: contextile
Version: 0.1.0
Summary: Manage, retrieve, and compact AI project instructions, lessons learned, and contextual rules for LLM workflows.
Author-email: Joab Leite <leitejoab@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/cereja-project/contextile
Project-URL: Documentation, https://github.com/cereja-project/contextile#readme
Project-URL: Repository, https://github.com/cereja-project/contextile
Project-URL: Issues, https://github.com/cereja-project/contextile/issues
Project-URL: Changelog, https://github.com/cereja-project/contextile/releases
Keywords: llm,ai,agents,context,prompt-engineering,instructions,project-context,lessons-learned,memory,retrieval,context-management,token-optimization,mcp,model-context-protocol,cli,developer-tools
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cereja
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: mcp>=1.0.0; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Provides-Extra: mcp
Requires-Dist: mcp>=1.0.0; extra == "mcp"
Dynamic: license-file

# Contextile

Contextile is a Python toolkit for managing, retrieving, and compacting AI project instructions, lessons learned, and contextual rules for LLM workflows.

The MVP focuses on a small local workflow:

- initialize a `.contextile/` workspace;
- store durable lessons in JSONL;
- validate lesson records;
- search relevant lessons for a task;
- build a compact Markdown context block for an LLM.

MCP support is planned as a thin optional layer on top of the core library.

## Install locally

```bash
pip install -e .
```

## Initialize a project

```bash
contextile init
```

This creates:

```text
.contextile/
  config.json
  lessons.jsonl
  instructions/
    project-context.md
    architecture-rules.md
    code-standards.md
    validation.md
```

## Add a lesson

```bash
contextile add-lesson \
  --id preserve-domain-terms \
  --when "Editing existing domain terms in code, docs, routes, schemas, enums, or API contracts." \
  --do "Preserve domain terms exactly as used in the project." \
  --avoid "Do not translate established domain terms." \
  --scope "Code, docs, API, DB, routes, enums, UI." \
  --tags domain,terminology,api,routes,enums
```

## Search lessons

```bash
contextile search "api validation reports" --limit 5
```

## Build compact context

```bash
contextile build-context \
  --task "Refactor API validation for reports" \
  --file src/schemas/par/relatorio.py \
  --tag api \
  --tag validation \
  --max-tokens 800
```

## Validate records

```bash
contextile validate
```

## Compact records

```bash
contextile compact
```

## Lesson JSONL schema

Each line in `.contextile/lessons.jsonl` is one lesson:

```json
{"id":"preserve-domain-terms","when":"Editing existing domain terms.","do":"Preserve terms exactly as used.","avoid":"Do not translate established terms.","scope":"Code, docs, API, DB, routes, enums, UI.","tags":["domain","terms","api"]}
```

Required fields:

- `id`
- `when`
- `do`
- `avoid`

Recommended fields:

- `scope`
- `tags`
- `why`
- `updated_at`
