zerottmm 0.1.0__py3-none-any.whl

zerottmm-0.1.0.dist-info/METADATA

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: zerottmm
+Version: 0.1.0
+Summary: Time‑to‑Mental‑Model: a local‑first code reading assistant (Phase A)
+Author-email: Gaurav Sood <contact@gsood.com>
+License-Expression: MIT
+Keywords: code-analysis,static-analysis,code-reading,python,ast
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+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 :: Code Generators
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: ui
+Requires-Dist: streamlit>=1.23; extra == "ui"
+Requires-Dist: openai>=1.0.0; extra == "ui"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Provides-Extra: ai
+Requires-Dist: openai>=1.0.0; extra == "ai"
+Provides-Extra: all
+Requires-Dist: streamlit>=1.23; extra == "all"
+Requires-Dist: pytest; extra == "all"
+Requires-Dist: openai>=1.0.0; extra == "all"
+
+# ttmm: Time‑to‑Mental‑Model
+
+`ttmm` is a local‑first code reading assistant designed to reduce the time it takes to load a mental model of a codebase.  It provides static indexing, simple call graph navigation, hotspot detection and dynamic tracing.  You can use it either from the command line or through a Streamlit web UI.
+
+**New**: `ttmm` now supports remote repositories via Git URLs and GitIngest integration, making it easy to analyze any public Python repository without cloning manually.
+
+## Key features (Phase A)
+
+* **Index your repository** – builds a lightweight SQLite database of all Python functions/methods, their definitions, references and coarse call edges using only the standard library.
+* **Remote repository support** – analyze any GitHub, GitLab, or Bitbucket repository directly via URL or GitIngest links without manual cloning.
+* **Hotspot detection** – computes a hotspot score by combining cyclomatic complexity and recent git churn to help you prioritise where to read first.
+* **Static call graph navigation** – shows callers and callees for any symbol using conservative AST analysis.  Attribute calls that cannot be resolved are marked as `<unresolved>`.
+* **Keyword search** – a tiny TF‑IDF engine lets you ask a natural language question and returns a minimal reading set of relevant symbols.
+* **Dynamic tracing** – run a module, function or script with `sys.settrace` to capture the actual call sequence executed at runtime and persist it in the database.
+
+## Installation
+
+Requirements:
+
+* Python 3.8 or later (except 3.9.7 due to Streamlit compatibility)
+* A `git` executable in your `PATH` if you want churn‑based hotspot scores
+
+Install from PyPI:
+
+```bash
+pip install zerottmm
+```
+
+Or install in development mode from this repository:
+
+```bash
+pip install -e .
+```
+
+To enable optional extras:
+
+* `[ui]` – install `streamlit` and `openai` for the web UI with AI features
+* `[test]` – install `pytest` for running the test suite  
+* `[ai]` – install `openai` for AI-enhanced analysis
+
+For example:
+
+```bash
+pip install zerottmm[ui,test]
+```
+
+## Command line usage
+
+After installation a `zerottmm` command will be available:
+
+```bash
+zerottmm index PATH_OR_URL        # index a Python repository (local or remote)
+zerottmm hotspots PATH            # show the top hotspots (default 10)
+zerottmm callers PATH SYMBOL
+zerottmm callees PATH SYMBOL
+zerottmm trace PATH [--module pkg.mod:func | --script file.py] [-- args...]
+zerottmm answer PATH "your question"
+```
+
+* **PATH_OR_URL** – local repository path, Git URL, or GitIngest URL
+* **PATH** – local repository path that has been indexed previously
+* **SYMBOL** – a fully‑qualified name like `package.module:Class.method` or `package.module:function`.
+* **--module** – run a function or module entry point (e.g. `package.module:main`) and trace calls within the repository.
+* **--script** – run an arbitrary Python script in the repository and trace calls.
+
+Use `zerottmm --help` for full documentation.
+
+## Examples
+
+Here are some examples analyzing popular Python repositories:
+
+### Analyze the Python requests library
+```bash
+# Index directly from GitHub
+zerottmm index https://github.com/psf/requests.git
+
+# Find hotspots (complex functions with high churn)
+zerottmm hotspots /tmp/ttmm_repo_*/
+# Output: PreparedRequest.prepare_body, super_len, RequestEncodingMixin._encode_files
+
+# Ask natural language questions  
+zerottmm answer /tmp/ttmm_repo_*/ "how to make HTTP requests"
+# Output: HTTPAdapter.send, Session.request, HTTPAdapter.cert_verify
+```
+
+### Analyze a mathematical optimization library
+```bash  
+# Index a specialized repo via GitIngest URL
+zerottmm index "https://gitingest.com/?url=https://github.com/finite-sample/rank_preserving_calibration"
+
+# Find the main algorithmic components
+zerottmm answer /tmp/ttmm_repo_*/ "main calibration algorithm"
+# Output: calibrate_dykstra, calibrate_admm, _isotonic_regression
+
+# Explore function relationships
+zerottmm callers /tmp/ttmm_repo_*/ "calibrate_dykstra"  
+# Shows all the places this core algorithm is used
+```
+
+### Analyze FastAPI core (subpath example)
+```bash
+# Index just the FastAPI core module using GitIngest subpath
+zerottmm index "https://gitingest.com/?url=https://github.com/tiangolo/fastapi&subpath=fastapi"
+
+# Find entry points and main interfaces
+zerottmm answer /tmp/ttmm_repo_*/ "main application interface"
+```
+
+## Streamlit UI
+
+A simple web UI is provided under `app/app.py`.  To run it locally:
+
+```bash
+pip install -e .[ui]
+streamlit run app/app.py
+```
+
+The app allows you to index repositories (local or remote via GitIngest), explore hotspots, get AI-powered insights, and search interactively. Features include:
+
+* **Repository indexing** from local paths, Git URLs, or GitIngest links
+* **Automatic repository summary** with key metrics and analysis
+* **AI-enhanced analysis** with OpenAI integration (optional)
+* **Hotspot detection** and complexity analysis
+* **Natural language search** over code symbols
+
+The app is designed to run on [Streamlit Community Cloud](https://streamlit.io/cloud) – simply push this repository to GitHub and deploy the app by pointing to `app/app.py`. The `requirements.txt` file ensures all dependencies (including OpenAI) are automatically installed.
+
+## Development & tests
+
+Tests live in `tests/test_ttmm.py` and cover indexing, hotspot scoring and search.  To run them:
+
+```bash
+pip install -e .[test]
+pytest -q
+```
+
+Continuous integration is configured via `.github/workflows/ci.yml` to run the test suite on Python 3.8 through 3.12.  If you fork this repository on GitHub the workflow will execute automatically.
+
+## Limitations
+
+* Phase A supports Python only and uses conservative static analysis.  Many dynamic method calls cannot be resolved statically; these appear as `<unresolved>` in the call graph.
+* Hotspot scores require `git` to compute churn – if `git` is not installed or the directory is not a git repository, churn is assumed to be zero.
+* Dynamic tracing only captures calls within the repository root.  Calls to the standard library or external packages are ignored.
+
+Future phases (not implemented here) would add richer language support, deeper type‑aware call resolution and integration with your editor.

zerottmm-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+zerottmm/__init__.py,sha256=kVasgoTJFcM2iIoN-BsYfDo0uHHEU59lVuBRPnKHUBI,1274
+zerottmm/ai_analysis.py,sha256=WGe_YcPlykze182AMRylaCxvNduPDTroqtA3LjX7qwc,4773
+zerottmm/cli.py,sha256=_X35_v6-eTvTVeEl5da59e_hfkLenoULwnGRRJe3xEw,7536
+zerottmm/gitingest.py,sha256=7jGGk_LJbdcyjSEt9rghX8qnPjLhec9Rr4I6Odsv70I,6504
+zerottmm/gitutils.py,sha256=3KFeRklnLoYBmH14BLC2YTjfJlv-r9Nl2CJilPnW3CQ,3810
+zerottmm/index.py,sha256=5Th_7jOENhAMJbHG-7nAoDsfIsATmenPQxdmegDvAKg,6595
+zerottmm/metrics.py,sha256=dmyk-qal3vH0O1JIb9x9D_sSeGzB9ii7A4K0E-wI86U,2115
+zerottmm/search.py,sha256=PG3RV4z7c9PstkSgLLc3WGM70sKKTEo_PVak90TEwWk,4399
+zerottmm/store.py,sha256=u_1CcRaIofXsvpAf4O8of5i5TkjjMiwIHY5NLqS85So,13198
+zerottmm/trace.py,sha256=Nlw621J7_JpjEmJeu0KU05dB58LsbyiMO009zojUUo8,6691
+zerottmm-0.1.0.dist-info/METADATA,sha256=FqKxiRGI2RWOay4kVTaQmLmaGlU0smxNb3q1dpDsXrc,7523
+zerottmm-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+zerottmm-0.1.0.dist-info/entry_points.txt,sha256=SB5P12FcxrIQCaZbfpg9EvGqX4NM4ijWMVzUgLXNJjA,47
+zerottmm-0.1.0.dist-info/top_level.txt,sha256=BNjiqDdE-_XlhpjAe8rlS3ocL53EG-nqaBmrxN2bCnQ,9
+zerottmm-0.1.0.dist-info/RECORD,,

zerottmm-0.1.0.dist-info/WHEEL

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

zerottmm-0.1.0.dist-info/entry_points.txt

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

zerottmm-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+zerottmm