🚀 Big News: Socket Acquires Coana to Bring Reachability Analysis to Every Appsec Team.Learn more
Socket
DemoInstallSign in
Socket

kotemari

Package Overview
Dependencies
Maintainers
1
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

kotemari

Kotemari: A Python library and CLI tool to analyze codebases, understand dependencies, and generate accurate context for LLMs. Simplifies RAG generation for coding tasks.

0.1.0
PyPI
Maintainers
1

Kotemari 🪄

PyPI version Build Status Code Coverage License: MIT

Kotemari is a Python library designed to analyze your Python project structure, understand dependencies, and intelligently generate context for Large Language Models (LLMs) like GPT. 🧠 Its core purpose is to be integrated into other development tools (like IDE extensions, analysis scripts, or chat interfaces) to provide on-demand project insights and context. It also features real-time file monitoring to keep the analysis up-to-date effortlessly! ✨

🤔 Why Kotemari?

Integrating project understanding capabilities into tools or automating context generation for LLMs can be complex. Kotemari simplifies this by providing a robust Python API that:

  • 🎯 Delivers Smart Context: Generate concise context strings including only necessary files and their dependencies via simple API calls.
  • 🔄 Stays Up-to-Date: Offers background file monitoring and automatic cache/dependency updates, ensuring the information provided by the API is current.
  • 🔍 Provides Deep Insight: Exposes methods to access detailed dependency information (direct and reverse) derived from analyzing Python import statements.
  • ⚙️ Offers Flexibility: Easily configurable through Python arguments or an optional .kotemari.yml file, respecting .gitignore rules.
  • 🧩 Enables Integration: Designed to be easily embedded into your custom Python applications and development workflows.

Kotemari empowers your tools by providing sophisticated project analysis capabilities through a simple and effective Python API. 🎉

🚀 Installation

Kotemari is currently under development. To install the development version:

  • Clone the repository:
    git clone https://github.com/<YOUR_GITHUB_USERNAME>/kotemari.git
    cd kotemari
    
  • Create a virtual environment:
    # Using venv
    python -m venv .venv
    source .venv/bin/activate # On Windows use `.venv\Scripts\activate`
    
    # Or using uv (recommended)
    uv venv
    source .venv/bin/activate # On Windows use `.venv\Scripts\activate`
    
  • Install the package in editable mode:
    # Using pip
    pip install -e .[dev]
    
    # Or using uv
    uv pip install -e .[dev]
    

(Once released, installation will be as simple as pip install kotemari)

✨ Usage (Python API)

Using Kotemari in your Python code is straightforward:

import logging
from pathlib import Path
from kotemari import Kotemari

# Optional: Configure logging to see Kotemari's internal activity
logging.basicConfig(level=logging.INFO, format='[%(levelname)s] %(name)s: %(message)s')

# 1. Initialize Kotemari with your project's root directory
project_path = Path("./your/project/path") # <-- Change this!
kotemari = Kotemari(project_path)

# 2. Analyze the project (builds initial cache and dependency graph)
print("Analyzing project...")
kotemari.analyze_project()
print("Analysis complete!")

# 3. Get a list of analyzed files (FileInfo objects)
print("\nAnalyzed Files:")
all_files = kotemari.list_files()
for file_info in all_files[:5]: # Print first 5 for brevity
    print(f"- {file_info.path.relative_to(project_path)} (Hash: {file_info.hash[:7]}...)")

# 4. Get dependencies of a specific file
target_file = project_path / "src/module_a.py" # Example
print(f"\nDependencies of {target_file.name}:")
try:
    dependencies = kotemari.get_dependencies(target_file)
    if dependencies:
        for dep_path in dependencies:
            print(f"- {dep_path.relative_to(project_path)}")
    else:
        print("- No direct dependencies found.")
except FileNotFoundError:
    print(f"- File {target_file.name} not found in analysis results.")

# 5. Get files that depend ON a specific file (reverse dependencies)
dependent_on_file = project_path / "src/utils.py" # Example
print(f"\nFiles depending on {dependent_on_file.name}:")
try:
    reverse_deps = kotemari.get_reverse_dependencies(dependent_on_file)
    if reverse_deps:
        for rev_dep_path in reverse_deps:
            print(f"- {rev_dep_path.relative_to(project_path)}")
    else:
        print("- No files directly depend on this.")
except FileNotFoundError:
    print(f"- File {dependent_on_file.name} not found in analysis results.")

# 6. Generate formatted context for LLM (target file + dependencies)
context_file = project_path / "src/main_logic.py" # Example
print(f"\nGenerating context for {context_file.name}:")
try:
    context_string = kotemari.get_context(context_file)
    print("--- Context Start ---")
    print(context_string[:500] + "... (truncated)") # Print start for brevity
    print("--- Context End ---")
except FileNotFoundError:
    print(f"- File {context_file.name} not found.")
except Exception as e:
    print(f"An error occurred: {e}")

# 7. Optional: Start background file watching for real-time updates
# Kotemari will automatically update its internal state when files change.
print("\nStarting file watcher (runs in background)...")
kotemari.start_watching() 

# --- Your application logic here --- 
# You can now query kotemari methods (list_files, get_dependencies, etc.) 
# and get up-to-date results reflecting any file changes.

print("Watcher is running. Modify project files to see updates (check logs if INFO enabled).")
input("Press Enter to stop watching and exit...\n")

print("Stopping watcher...")
kotemari.stop_watching()
print("Watcher stopped.")

Key API Methods:

  • Kotemari(project_root, config_path=None, use_cache=True, log_level=logging.WARNING): Initialize the analyzer.
  • analyze_project(): Performs the initial full analysis.
  • list_files(): Returns List[FileInfo] for all tracked files.
  • get_dependencies(file_path: Path): Returns Set[Path] of files the target file imports.
  • get_reverse_dependencies(file_path: Path): Returns Set[Path] of files that import the target file.
  • get_context(file_path: Path, include_dependencies=True, formatter=...): Generates a context string.
  • start_watching() / stop_watching(): Controls the background file monitor.
  • clear_cache(): Removes cached analysis results.

🛠️ CLI Usage (Optional)

Kotemari also provides a basic command-line interface for quick checks and simple tasks:

# Activate environment
source .venv/bin/activate # Or .venv\Scripts\activate

# Basic commands
kotemari analyze
kotemari list
kotemari tree
kotemari dependencies <path/to/file.py>
kotemari context <path/to/file1.py> [<path/to/file2.py>...]

# Get help
kotemari --help
kotemari analyze --help

🔧 Development

Interested in contributing?

  • Set up the environment (See Installation section).
  • Run tests:
    pytest
    
  • Check code coverage:
    pytest --cov=src/kotemari
    

Please refer to CONTRIBUTING.md (to be created) for contribution guidelines.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

💻 Supported Environments

  • Python: 3.8+
  • OS: Windows, macOS, Linux (tested primarily on Windows)

Let Kotemari simplify your Python project analysis! 🌳

Keywords

context generation

FAQs

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts