crack-jee 0.1.0__py3-none-any.whl

bkt.py

@@ -0,0 +1,45 @@
+"""Bayesian Knowledge Tracing: pure functions, no DB dependency.
+
+Fixed literature-default parameters, per ex1.md §7.2 — not fitted on her
+data (not enough volume to fit reliably). Same defaults used by the
+synthetic-KT research track's BKTParameters for consistency across the repo.
+"""
+from typing import Literal
+
+P_L0 = 0.20  # initial mastery prior
+P_T = 0.10  # learning/transition rate
+P_S = 0.10  # slip rate
+P_G = 0.25  # guess rate
+
+Result = Literal["correct", "wrong", "unattempted"]
+
+
+def update_mastery(prior: float, result: Result) -> float:
+    """Closed-form Bayesian update + transition. `unattempted` carries no
+    evidence about knowledge (she didn't try), so mastery passes through
+    unchanged — only correct/wrong update the posterior."""
+    if result == "unattempted":
+        return prior
+
+    if result == "correct":
+        numerator = prior * (1.0 - P_S)
+        denominator = numerator + (1.0 - prior) * P_G
+    else:
+        numerator = prior * P_S
+        denominator = numerator + (1.0 - prior) * (1.0 - P_G)
+
+    posterior = numerator / denominator if denominator > 0 else prior
+    return posterior + (1.0 - posterior) * P_T
+
+
+def apply_decay(mastery: float, days_since_last_attempt: float) -> float:
+    """Simple time-decay nudge (ex1.md §7.3) — not a fitted forgetting
+    curve. 14-day grace period, then ×0.97 per additional full week idle,
+    floored at 0.3 so it never implies "never learned." Read-time only,
+    never written back."""
+    grace_days = 14
+    floor = 0.3
+    if days_since_last_attempt <= grace_days:
+        return mastery
+    idle_weeks = (days_since_last_attempt - grace_days) / 7.0
+    return floor + (mastery - floor) * (0.97**idle_weeks)

crack_jee-0.1.0.dist-info/METADATA

@@ -0,0 +1,182 @@
+Metadata-Version: 2.4
+Name: crack-jee
+Version: 0.1.0
+Summary: A personal, local MCP server that acts as a performance coach for a JEE aspirant
+Author-email: Sai Rithvik Mahankali <rikkumahan07@gmail.com>
+License-Expression: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastmcp>=2.0.0
+Dynamic: license-file
+
+<p align="center">
+  <img src="assets/banner.png" alt="CRACK-JEE — Plan smarter, Prepare better" width="100%">
+</p>
+
+<p align="center">
+  <img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-red">
+  <img alt="Python 3.10+" src="https://img.shields.io/badge/python-3.10%2B-red">
+  <img alt="Protocol: MCP" src="https://img.shields.io/badge/protocol-MCP-black">
+  <img alt="Local-first" src="https://img.shields.io/badge/data-local--only-black">
+</p>
+
+<p align="center">
+  A personal AI coach for JEE aspirants, built as an MCP server. Not a tutor,
+  not a chatbot with a syllabus bolted on — it turns raw test results into a
+  closed feedback loop: log what happened, find the patterns a single test
+  report can never show, get a concrete next study plan, and verify whether
+  it actually worked on the next test.
+</p>
+
+<p align="center">
+  Free. Local. No subscription, no hosting bill, no data leaving your machine
+  except to whatever LLM chat client you connect it to.
+</p>
+
+---
+
+## Why
+
+Coaching institute reports are siloed — each test is graded in isolation. Two
+things never happen on their own:
+
+1. **Cross-test pattern mining.** The same mistake, on the same concept,
+   across five different tests over two months, looks like five unrelated
+   bad days unless something is tracking it. CRACK-JEE finds it.
+2. **Closed-loop verification.** A coach tells you to fix something. Nobody
+   goes back after the next test and checks whether it worked. CRACK-JEE
+   does, automatically, every time.
+
+Everything in between — mastery estimation, what's about to be forgotten,
+where you're burning time versus actually stuck, skip-vs-wrong strategy
+under negative marking — is plain deterministic code, not a trained model.
+An LLM only extracts messy input into structured data and writes the study
+plan in your coach's voice; every number it reasons over comes from
+arithmetic and SQL, not inference.
+
+---
+
+## How it works
+
+```
+you describe a test  →  LLM extracts structured data  →  local SQLite log
+                                                                │
+                                                                ▼
+                                            deterministic analytics engine
+                                     (mastery, weak spots, revision timing,
+                                      time-on-task, skip/negative-marking)
+                                                                │
+                                                                ▼
+                                     LLM reasons over it, writes a real plan
+                                                                │
+                                                                ▼
+                                          next test's results close the loop
+```
+
+Connect it to any MCP-capable chat client (Claude Desktop, Qwen Desktop,
+etc.) and just talk to it like a coach — describe results in whatever format
+you have, ask what to study, mention an upcoming exam and its syllabus.
+
+---
+
+## What it tracks
+
+| Capability | What it answers |
+|---|---|
+| Weak topics | Which concepts have the worst accuracy — and separates "skipped wisely" from "guessed and got it wrong," since JEE's negative marking makes those different problems |
+| Recurring mistakes | Which error types repeat on the same concept across multiple tests — the thing a single per-test report can't show |
+| Concept mastery (BKT) | A real probability of knowing each concept, updated after every attempt, with retention decay applied over time |
+| Revision due | What's about to be forgotten and should be revised before that happens |
+| Time patterns | Whether you're genuinely stuck on a concept (spending much longer on wrong answers) versus just making quick errors |
+| Student profile | Overall pace, time-management tendencies, and subject strengths across everything logged so far |
+| Exam planning | A full study plan for an upcoming exam's syllabus, accounting for topics you haven't touched yet |
+| Progress verification | Before/after accuracy on a concept or exam once a plan has been acted on — the closed loop |
+
+17 MCP tools total, covering logging, analytics, daily planning, exam
+planning, and progress verification. See [`docs/plan.md`](docs/plan.md) for
+the full build history and [`docs/chat-client-system-prompt.md`](docs/chat-client-system-prompt.md)
+for exactly how a connected client is expected to use them.
+
+---
+
+## Setup
+
+Requires [Python ≥ 3.10](https://www.python.org/) and
+[`uv`](https://github.com/astral-sh/uv).
+
+```bash
+uv sync
+uv run python src/server.py   # runs the server on stdio for local dev
+```
+
+Connect it from any MCP client by pointing it at that command, e.g.:
+
+```json
+{
+  "mcpServers": {
+    "crack-jee": {
+      "command": "uv",
+      "args": ["run", "--directory", "C:/path/to/CRACK-JEE", "python", "src/server.py"]
+    }
+  }
+}
+```
+
+Once published to PyPI, `uvx crack-jee` will work with zero
+local install — see [`docs/setup.md`](docs/setup.md) for exact commands and
+[`docs/production-readiness-notes.md`](docs/production-readiness-notes.md)
+for what's left before that.
+
+### Test
+
+```bash
+uv run pytest tests/ -v
+```
+
+---
+
+## Design principles
+
+- **Deterministic core, LLM at the edges.** The LLM extracts and writes
+  plans in natural language; every mastery estimate, ranking, and trend is
+  plain code — reproducible, debuggable, and free to run.
+- **Fixed-parameter BKT, not a trained model.** A single student's few
+  hundred attempts is a different data regime than the population-scale
+  data DKT/AKT/SAINT-style models need. See [`ex1.md §7`](ex1.md) for the
+  full reasoning, and [`research/synthetic_jee_kt/`](research/synthetic_jee_kt/)
+  for the benchmark that backs the decision.
+- **Never invents an answer.** If a tool call fails on bad input or
+  something's ambiguous, the client is instructed to ask rather than guess
+  and log something wrong into your history.
+- **Exam-agnostic.** Nothing hardcodes JEE's subjects or syllabus — concept
+  and subject are free-text fields set by whoever logs the data. Works the
+  same for any exam; JEE is just what it was built for.
+
+Full rationale for every non-obvious decision, including rejected
+approaches, is in [`docs/decisions.md`](docs/decisions.md) (append-only
+log) and [`ex1.md`](ex1.md).
+
+---
+
+## Project structure
+
+```
+CRACK-JEE/
+├── src/
+│   ├── server.py       # FastMCP server entrypoint
+│   ├── db.py            # SQLite schema, queries, concept dedup
+│   ├── bkt.py            # BKT closed-form Bayesian update + retention decay
+│   └── tools/            # One file per MCP tool, registered in server.py
+├── tests/                # Test suite (pytest)
+├── research/synthetic_jee_kt/   # Independent KT-model benchmark, not part of the server
+├── docs/                 # Design docs, decision log, setup instructions
+├── presentation/         # Hackathon deck source + related notes, not part of the server
+└── pyproject.toml
+```
+
+---
+
+## License
+
+MIT — see [`LICENSE`](LICENSE).

crack_jee-0.1.0.dist-info/RECORD

@@ -0,0 +1,26 @@
+bkt.py,sha256=wjebwuIpXdSXulMRQg_xc7xM4SikxnFZ3YIICCRvCcA,1714
+db.py,sha256=JNyk9oMQsDv0IGMeFbCqo6hxnRYrGDUQ2B8QyxUMo4s,28181
+server.py,sha256=mdafy3nEpUembOACVZTT5NflbCk6gV_GIbHncR5W5tM,4624
+crack_jee-0.1.0.dist-info/licenses/LICENSE,sha256=poByJUxS58Kbv2OVEqF3QjAonmaMZ1H4_l381uEvTqE,1078
+tools/__init__.py,sha256=KFeWJ--sooijvgQROqL9tT72tPu79brfJAHflQcZr1A,30
+tools/end_study_session.py,sha256=JgK23gExlZg5q6METO1DngZ_Ze04UxR5BDbV4POPU3M,643
+tools/generate_daily_plan.py,sha256=TE_uoZjkaKR6m5cwPZURV8PyLvuEDpPjV5qlZMLI974,781
+tools/generate_exam_plan.py,sha256=yFy7Sxq4l5Kz6KbbXzykJgWGiv9zGL6eBm6P49KZqhk,825
+tools/get_concept_state.py,sha256=c1wlUtWXvKh5lX-r4G4Hwvppe-KFKxHHWw8co_rsON8,661
+tools/get_exam.py,sha256=Rgcp0Cqy7Unn0AI3NYt-MsKmyln4B3UfmTeuuQHC1AM,579
+tools/get_exam_progress.py,sha256=ya6D3eNqZk1VgVf8IOeXlnNyIm_y3CYar-ELQDPgsH8,643
+tools/get_progress.py,sha256=xiKl2Sdw4paQ8M3uLg8FBrgiUE7szD6ME8YhjPZzMBY,570
+tools/get_recurring_mistakes.py,sha256=Px6N_6GvcNFd1KYbp5rlsPyTb48Zi6Ohj4K8E6wS76s,714
+tools/get_revision_due.py,sha256=Hfpr1kmw7N1itbpe34JRoFGXB5nrPhXlaVrXfYvNoaw,737
+tools/get_student_profile.py,sha256=rGdySPgAqgNWBTSGuNbl_ewYfVyskf9yIQtsFOGd3Sw,765
+tools/get_time_patterns.py,sha256=DgYUGYbLo0xIpKUEt0mP6kEqvqVqgV-7VJJEYzZBQVw,620
+tools/get_weak_topics.py,sha256=VdZafoB9U7h3rO_TybuSJdjwlGbY03HjQg4lpv0PKQI,760
+tools/list_concepts.py,sha256=91E5X9nNfTaJsGK2yw96nIarPyFTreEl0KyoObXhJxc,656
+tools/list_exams.py,sha256=MdA5A6lj3CA5h54w0-BcKC99JBiDpWZYrgEZqOfhJVM,510
+tools/log_performance_input.py,sha256=O3XllMyBPc0vp2nlDOS3aWl1S-EUz0QONNxZyCox928,2202
+tools/set_exam.py,sha256=OM-MWMKa6zAoCMLdIdW-I19bvB_VAhtpcAGPc1IpHmc,782
+crack_jee-0.1.0.dist-info/METADATA,sha256=Qww5jifyQTTGBCsIUNEA2Gx8m4_5VoXXlUdwiuyj42E,7675
+crack_jee-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+crack_jee-0.1.0.dist-info/entry_points.txt,sha256=i4NPTvFmHXOcl_zsOuh0L0T6cthZbxiUvn0-lbXZ1vI,42
+crack_jee-0.1.0.dist-info/top_level.txt,sha256=1kcMEyC649wDx7HVrlAr9smtCQA_Mjo-35gyIXCWo80,20
+crack_jee-0.1.0.dist-info/RECORD,,

crack_jee-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
+

crack_jee-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+crack-jee = server:main

crack_jee-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sai Rithvik Mahankali
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

crack_jee-0.1.0.dist-info/top_level.txt

@@ -0,0 +1,4 @@
+bkt
+db
+server
+tools