chronicle-devkit 0.1.0__py3-none-any.whl

chronicle_devkit-0.1.0.dist-info/METADATA

@@ -0,0 +1,233 @@
+Metadata-Version: 2.4
+Name: chronicle-devkit
+Version: 0.1.0
+Summary: A local first developer intelligence tool
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: typer>=0.16
+Requires-Dist: tomli-w>=1.2.0
+Requires-Dist: openai>=3.6.0
+Requires-Dist: nltk>=3.10.3
+Requires-Dist: google-genai>=2.20.0
+Requires-Dist: keyring>=25.7.0
+Requires-Dist: tomli>=2.0.0; python_version < "3.11"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+
+# Chronicle
+
+**Local-first developer intelligence.** Chronicle records how a software project changes over time, turns that history into signals, and lets you ask questions about it — all stored and analyzed on your own machine.
+
+Chronicle fits naturally into your existing workflow. Point it at a Git project, and it:
+
+1. **Scans** your project's history into structured *observations* (git commits, Django migrations).
+2. **Analyzes** those observations into actionable *findings* (new files, changed schema fields …).
+3. **Interprets** the collected history with AI, answering questions in plain language.
+
+## How it works
+
+```
+git history ──► scan ──► observations ──► analyze ──► findings ──► interpret (AI) ──► answers
+Django migrations ─┘                     local SQLite     ▲
+                                                     keywords + related commits
+```
+
+- **Local-first** — everything lives in a `.chronicle/` folder inside your project. No accounts, no cloud sync, no telemetry. Your `chronicle.db` stays yours.
+- **Incremental** — Chronicle remembers how far it got (`scan_state` for scanners, `analysis_state` for analyzers) so repeated runs only process what's new.
+- **Extensible** — scanners (`Scanner`) and analyzers (`BaseAnalyzer`) are pluggable; providers are pluggable too (OpenAI / Gemini).
+
+## Requirements
+
+- **Python 3.10+**
+- A **Git** repository (the project root is detected by walking up to the nearest `.git` directory)
+- `pip` via the `dev` extra for running tests
+
+## Installation
+
+```bash
+# clone and enter the repository
+git clone https://github.com/Sakshyam-Xtha/Chronicle.git
+cd Chronicle
+
+# create a virtual environment (optional but recommended)
+python -m venv .venv
+source .venv/bin/activate
+
+# install in editable mode (includes the `chronicle` command)
+pip install -e ".[dev]"
+```
+
+Verify the CLI is on your path:
+
+```bash
+chronicle version   # -> Chronicle 0.1.0
+```
+
+## Quick start
+
+```bash
+# 1. Initialize Chronicle in a project (creates .chronicle/ + local DB)
+cd /path/to/your/project
+chronicle init
+
+# 2. Scan the project history into observations
+chronicle scan
+
+# 3. Browse what was recorded
+chronicle show
+chronicle show --id 1
+
+# 4. Analyze observations into findings
+chronicle analyze
+
+# 5. Ask questions about your history (requires an AI provider/key)
+chronicle interpret --question "When did we add the User model?"
+```
+
+> `init`, `scan`, and `show` need no configuration. Only `interpret` requires an AI provider.
+
+## Command reference
+
+| Command | Description |
+| --- | --- |
+| `chronicle init` | Create the `.chronicle/` directory and initialize the local database |
+| `chronicle scan` | Scan project history into observations (git commits, Django migrations) |
+| `chronicle show` | List all observations; `--id <n>` shows one observation in detail |
+| `chronicle analyze` | Turn observations into findings via the installed analyzers |
+| `chronicle interpret --question "<text>"` | Ask an AI-backed question about the project history |
+| `chronicle config` | View current configuration; `set provider` / `set model` to configure AI |
+| `chronicle status` | Show whether the project is initialized and detected |
+| `chronicle version` | Print the Chronicle version |
+
+### `chronicle status`
+
+```bash
+$ chronicle status
+Project: my-project
+Root: /path/to/my-project
+Git: detected
+Chronicle: initialized
+Configuration: found
+```
+
+### `chronicle show`
+
+Without arguments it prints a compact table of all observations. With `--id <n>` it renders a detailed view:
+
+```text
+Observation #1
+────────────────────────────────────────────
+Source:       git
+Type:         commit
+External ID:  9f8d3a1
+Timestamp:    2026-08-21 12:00:00 UTC
+
+Data
+────────────────────────────────────────────
+```
+Migration observations additionally show **App**, **Migration**, **Dependencies**, and **Operations** (model / field per operation).
+
+## Configuring AI (for `interpret`)
+
+Chronicle reads its configuration from `.chronicle/config.toml`:
+
+```toml
+[chronicle]
+version = 1
+
+[ai]
+provider = ""
+model = ""
+```
+
+Set the provider and model:
+
+```bash
+chronicle config set provider openai
+chronicle config set model gpt-4o
+```
+
+Then export your API key as an environment variable:
+
+```bash
+export OPENAI_API_KEY="sk-..."     # provider: openai
+export GEMINI_API_KEY="..."        # provider: gemini
+```
+
+Check everything is wired up:
+
+```bash
+chronicle config
+```
+
+## What gets recorded
+
+### Git commits (`scan`)
+
+Each commit becomes an observation with:
+
+- `hash`, `message`, `author`
+- `parents` (empty for the root commit, one or more for merges)
+- `changes` — per-file **status** (`A` added, `M` modified, `D` deleted) and **path**
+
+### Django migrations (`scan`)
+
+Every `migrations/*.py` file (ignoring `.git`, `.venv`, `venv`, `env`, `node_modules`, `__pycache__`) is parsed with `ast` into an observation with:
+
+- `app` (application label), `name` (migration name)
+- `dependencies`
+- `operations` — e.g. `AddField`, `RemoveField` with model / field details
+
+### Findings (`analyze`)
+
+Analyzers turn observations into findings:
+
+- **GitAnalyzer** — flags newly created files (`A`) with `severity: info`
+- **DjangoMigrationAnalyzer** — flags `RemoveField` (`warning`) and `AddField` (`info`) operations
+
+## How interpretation works
+
+`chronicle interpret` does **not** dump everything at the model. It:
+
+1. Tokenizes your question and drops stop words to extract keywords.
+2. Scores every finding by how well it matches those keywords (title, message, data).
+3. Picks the top 10 findings and their related git commits (e.g. the commit that introduced a migration).
+4. Builds a prompt with only that focused context and asks the configured provider.
+
+## Project layout
+
+```
+src/chronicle/
+├── ai/              # AI provider abstraction (OpenAI, Gemini, factory)
+├── analysis/        # analyzers + engine that turn observations into findings
+├── cli/             # Typer CLI commands (`scan`, `show`, `analyze`, …)
+├── config/          # config.toml management + API key resolution
+├── integrations/    # thin wrappers (e.g. git)
+├── interpretation/  # question -> context -> prompt -> AI response
+├── project/         # discovery, initialization, status
+├── scanning/        # scanners + engine that collect observations
+│   └── scanners/    # git, django_migrations and their models
+└── storage/         # SQLite repositories + schema
+```
+
+## Development
+
+Run the test suite:
+
+```bash
+pip install -e ".[dev]"
+pytest test/
+```
+
+The suite is split into:
+
+- `test/unit/` — fast, mocked tests (parsing, storage, contexts, models)
+- `test/integration/` — real-git and end-to-end CLI tests (incremental scan checkpoints, migration parsing, merge parents)
+
+## Roadmap / status
+
+Chronicle is an early-stage local-first tool (`0.1.0`). Current scanners cover **git** and **Django migrations**; analyzers cover **git file additions** and **Django schema changes**; AI interpretation supports **OpenAI** and **Gemini**.
+
+## License
+
+Not yet specified.

chronicle_devkit-0.1.0.dist-info/RECORD

@@ -0,0 +1,61 @@
+chronicle/__init__.py,sha256=Pru0BlFBASFCFo7McHdohtKkUtgMPDwbGfyUZlE2_Vw,21
+chronicle/ai/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+chronicle/ai/base.py,sha256=CAbFspewJ3w-ZnexVNCqyPraNoi5jP_FaYpWY7UmUBY,208
+chronicle/ai/factory.py,sha256=hYCJIYI_DSN1lgIZo7zEX_5sAIeJ_5rfNLyFrNTfZUA,558
+chronicle/ai/google_ai.py,sha256=aOXmtdiR0r5lqZ2_HyaOhQac3MLx4uIuzqRgzLryW8k,494
+chronicle/ai/openai.py,sha256=29u4-4vG6KKLOJc5XddMevYEXrk4LJaoIE5Tm2VoQ4c,432
+chronicle/analysis/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+chronicle/analysis/context.py,sha256=bT2BQyjUnWQ2wbasbwe5JoozHRM_AIM2pByR2i7f8Fs,372
+chronicle/analysis/engine.py,sha256=xDjAWhLURBgva0NjbDZ9SKknw7viwCXQHdEOuJMPgpw,595
+chronicle/analysis/analyzers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+chronicle/analysis/analyzers/base.py,sha256=Ce8n36Onimo3--abrLgtXXBVan40VyOdH-Hh82E-ZJ8,511
+chronicle/analysis/analyzers/django_migrations.py,sha256=jUlm4-2F6dry2b3D4z3g0rIwPW99HlIaixOL64uE89Y,2533
+chronicle/analysis/analyzers/git.py,sha256=j83GpD5JL2Lg8EJKp9YrBd4RBEDLtK6Fpm5qa-n5VSI,1410
+chronicle/cli/__init__.py,sha256=L6zbQIZKsAP-Knhm6fBcQFPoVdIDuejxze60qX23jiw,21
+chronicle/cli/main.py,sha256=uZITs7cfhJg9oVHmAdpwis7-Faii8HLBWxCooF4sCSk,853
+chronicle/cli/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+chronicle/cli/commands/analyze.py,sha256=CmmJ9JVwm6PTar-CckJIn2GqEQ7XV4ONI2dvAMsadSw,2561
+chronicle/cli/commands/config.py,sha256=aTYo35nN8fGRlqXkSs-9k8580E7W3eQ-uHf_D2zvd-E,2474
+chronicle/cli/commands/init.py,sha256=9Ah1_Jm7c-hNU1ZH6310p_Vz-EmqCf3LsjzCUKGJc9Y,1863
+chronicle/cli/commands/interpret.py,sha256=6LxpsMvtwTWkDyd9JmkDaKX9A4IIvH6gzmPKzGdv6UM,1809
+chronicle/cli/commands/scan.py,sha256=1z-uFXclg_ZQRH6pp3cYwoZJDJtkczm9VSwLiXwPW7s,2816
+chronicle/cli/commands/show.py,sha256=lr47IaMakNdUnp_iAESZv_LkG2azrcJTncj6glNx57k,3313
+chronicle/cli/commands/status.py,sha256=M6TpEzFOAkuLDKUQIxe4CWViuQO14rmVKVzJ2Pzcuh0,881
+chronicle/cli/commands/version.py,sha256=3J1vrNKrLNP6s5isl5hTGhI7GZ-Dz1V3cO7kfnl1FvQ,138
+chronicle/config/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+chronicle/config/credentials.py,sha256=quu5dlHb4HZD4jJvVKZFskQE-6tf7XUum-WV6DvnQ7w,373
+chronicle/config/loader.py,sha256=Ew6_-W3ye_Vzu-judLz2-4REF-GLIMFqY4zvmGR33Is,584
+chronicle/config/manager.py,sha256=XX2AtDGkngLPpN8h5V0a8tBHJZi0knFsJCyNwRYrPGg,1212
+chronicle/integrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+chronicle/integrations/git.py,sha256=VhVRFYsTjqenqpcT6C1UrEAP9rCeDs5K3Qn0iVdhoP8,395
+chronicle/interpretation/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+chronicle/interpretation/context.py,sha256=TvDz-biT-RiR252BnT5suqbAZF0nAc7ExWVOYLL8ZfM,215
+chronicle/interpretation/context_builder.py,sha256=8xdxTZa6xFZB07dqJyjK5D7XHaeTqqPP4QZVBaug5Dg,4197
+chronicle/interpretation/interpreter.py,sha256=KDRUkMhkhrtRBbC2t5MbDELhLhnXDOk-N_mYqzUc4JM,468
+chronicle/interpretation/prompts.py,sha256=ekEe0Z1_BlSPO8F-V67GBHXbX54A5nBQeC7RnJTuA98,1150
+chronicle/project/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+chronicle/project/discovery.py,sha256=Rw3XJoFFYRRIgdkmQ0AbNKUzbsp16U2Rg3n0xLi5n4g,309
+chronicle/project/initializer.py,sha256=KawLd3fdCyki1eFADhzIJUawB0tyDUqS6HJtun7Oeyw,1474
+chronicle/project/status.py,sha256=UkKn5MFKVo3tmMQ3sm795AipcA7JP24d54TsZbfiYQ8,691
+chronicle/scanning/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+chronicle/scanning/context.py,sha256=jR6kfgFixlV96HQwW3gFVSnR6t44tk8vFbhxSXMoFzA,260
+chronicle/scanning/engine.py,sha256=YQXVElq4KAUcMh3edUUBzZLKOrcn1TO14QTHvqI3gpk,583
+chronicle/scanning/scanners/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+chronicle/scanning/scanners/base.py,sha256=PN6K9T3ozd0eDRvFjLIeSCq-CL747hfUx0DZsSJAkGY,489
+chronicle/scanning/scanners/django_migrations.py,sha256=S-HXuYB8T-ckrU70fcuxCu95UlvWYy6LWIQEH8PTJ8U,5336
+chronicle/scanning/scanners/django_model.py,sha256=QTY50VFwXsFPxy3Yo1Z2800p-KE5SxwmCGVvJfX8zSM,244
+chronicle/scanning/scanners/git.py,sha256=a66-uykyJatdrbnBOK4ZAq0EWp2__fzm2dPHM-bgfxs,2955
+chronicle/scanning/scanners/git_models.py,sha256=UdAAUcuylK-_gFfVyhN9M5ULJiXzkiXA350Jr4oTxy4,91
+chronicle/storage/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+chronicle/storage/analysis_state.py,sha256=0ygt7xD1b3L26YsOFHXUW7MpWD2wa7P336ehBBqrxOc,1143
+chronicle/storage/database.py,sha256=k6GCtRvA-TKRkotZTJ07kCRGizXt0l3IsDYaLphILcc,287
+chronicle/storage/findings.py,sha256=UWWI6--3UNbQ_azQeS-PagoEa17AvmM4WGgZI3uk9kc,1432
+chronicle/storage/models.py,sha256=DLPMOrd-YqOwJwY_dazXSobSe0VjrdOIYYEAD9lUo_I,380
+chronicle/storage/observations.py,sha256=ary3D-x44-7qw2nyq2E-RHdkl7UAXizISwzmPRxKt2w,2746
+chronicle/storage/scan_state.py,sha256=NjsJZPGrvkC3pttRoIgfWVeshwPgg3_5s_ZItZpbXOs,1123
+chronicle/storage/schema.py,sha256=3-BF09agnEpIMhXeyz8AWcztLG8ddDiQd5yIU7Bale0,1131
+chronicle_devkit-0.1.0.dist-info/METADATA,sha256=dMoWzBvPPfip5i-R2DtNARFoVXxhuCiKncxttcWV_68,7757
+chronicle_devkit-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+chronicle_devkit-0.1.0.dist-info/entry_points.txt,sha256=4Nyl9fwcb4SxUG-YcxJ7V5rRFbeXR7MsK7XpIFhpKKE,54
+chronicle_devkit-0.1.0.dist-info/top_level.txt,sha256=4BFZDl1VGI4Dov1YUkhT3azSPsLl1YU14GEzl3fEBD8,10
+chronicle_devkit-0.1.0.dist-info/RECORD,,

chronicle_devkit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

chronicle_devkit-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+chronicle = chronicle.cli.main:main

chronicle_devkit-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+chronicle