agenticstackfile 0.1.0__py3-none-any.whl

agenticstack/analyzer/base.py

@@ -0,0 +1,12 @@
+from abc import ABC, abstractmethod
+from pathlib import Path
+
+
+class BaseAnalyzer(ABC):
+
+    def __init__(self, root_path: Path):
+        self.root_path = root_path
+
+    @abstractmethod
+    def analyze(self) -> dict:
+        pass

agenticstack/analyzer/python.py

@@ -0,0 +1,136 @@
+import ast
+import os
+from pathlib import Path
+from .base import BaseAnalyzer
+import fnmatch
+
+FILE_PATTERNS = {
+    "models": ["model", "models"],
+    "views": ["view", "views"],
+    "serializers": ["serializer", "serializers"],
+    "services": ["service", "services"],
+    "tests": ["test", "tests"],
+    "admin": ["admin"],
+    "urls": ["url", "urls"],
+    "filters": ["filter", "filters"],
+    "tasks": ["task", "tasks"],
+    "utils": ["util", "utils", "helper", "helpers"],
+}
+
+
+class PythonAnalyzer(BaseAnalyzer):
+
+    def __init__(self, root_path: Path):
+        super().__init__(root_path)
+        self.results = {
+            "classes": [],
+            "functions": [],
+            "imports": [],
+            "file_map": {},
+            "errors": [],
+        }
+    
+    def _load_ignore_patterns(self) -> list:
+        ignore_file = self.root_path / ".agenticstackignore"
+        patterns = []
+
+        if not ignore_file.exists():
+            return patterns
+
+        for line in ignore_file.read_text(encoding="utf-8").splitlines():
+            line = line.strip()
+            if line and not line.startswith("#"):
+                patterns.append(line)
+
+        return patterns
+
+    def _is_ignored(self, path: Path, patterns: list) -> bool:
+        relative = str(path.relative_to(self.root_path))
+
+        for pattern in patterns:
+            if fnmatch.fnmatch(relative, pattern):
+                return True
+            if fnmatch.fnmatch(path.name, pattern):
+                return True
+
+        return False
+    
+    def _classify_file(self, filepath: str) -> str:
+        path = Path(filepath)
+        filename = path.stem.lower()
+        parent = path.parent.name.lower()
+
+        for file_type, patterns in FILE_PATTERNS.items():
+            for pattern in patterns:
+                if pattern in filename or pattern in parent:
+                    return file_type
+
+        return "other"
+    
+    def _parse_file(self, filepath: Path) -> None:
+        relative_path = str(filepath.relative_to(self.root_path))
+        file_type = self._classify_file(str(filepath))
+        self.results["file_map"][relative_path] = file_type
+
+        try:
+            source = filepath.read_text(encoding="utf-8")
+            tree = ast.parse(source)
+        except (SyntaxError, UnicodeDecodeError) as e:
+            self.results["errors"].append({
+                "file": relative_path,
+                "error": str(e)
+            })
+            return
+
+        for node in ast.walk(tree):
+            if isinstance(node, ast.ClassDef):
+                self.results["classes"].append({
+                    "name": node.name,
+                    "file": relative_path,
+                    "type": file_type,
+                    "line": node.lineno,
+                })
+            elif isinstance(node, ast.FunctionDef):
+                self.results["functions"].append({
+                    "name": node.name,
+                    "file": relative_path,
+                    "type": file_type,
+                    "line": node.lineno,
+                })
+            elif isinstance(node, ast.Import):
+                for alias in node.names:
+                    self.results["imports"].append({
+                        "name": alias.name,
+                        "file": relative_path,
+                    })
+            elif isinstance(node, ast.ImportFrom):
+                self.results["imports"].append({
+                    "name": f"from {node.module} import ...",
+                    "file": relative_path,
+                })
+    
+    def _get_python_files(self) -> list:
+        python_files = []
+        skip_dirs = {".venv", "__pycache__", ".git", "migrations", ".tox", "build", "dist"}
+        patterns = self._load_ignore_patterns()
+
+        for root, dirs, files in os.walk(self.root_path):
+            dirs[:] = [
+                d for d in dirs
+                if d not in skip_dirs
+                and not self._is_ignored(Path(root) / d, patterns)
+            ]
+            for file in files:
+                filepath = Path(root) / file
+                if file.endswith(".py") and not self._is_ignored(filepath, patterns):
+                    python_files.append(filepath)
+
+        return python_files
+    
+    def analyze(self) -> dict:
+        python_files = self._get_python_files()
+
+        for filepath in python_files:
+            self._parse_file(filepath)
+
+        return self.results

agenticstack/cli.py

@@ -0,0 +1,45 @@
+import click
+from pathlib import Path
+from .config import create_default_config, config_exists, write_config, read_config, create_default_ignore_file
+from .core import run
+
+
+@click.group()
+def main():
+    """AgenticStack — instant codebase map for AI agents."""
+    pass
+
+
+@main.command()
+@click.option("--api-key", default=None, help="Your LLM provider API key")
+@click.option("--provider", default=None, help="Provider: anthropic or openai")
+@click.option("--model", default=None, help="Model: default, fast, or smart")
+def init(api_key, provider, model):
+    """Initialize AgenticStack in this project."""
+    if config_exists():
+        click.echo("AgenticStack: Config already exists. Use 'agenticstack update' to refresh.")
+        return
+
+    create_default_config()
+    click.echo("AgenticStack: Created .agenticstack.ini")
+    create_default_ignore_file()
+    click.echo("AgenticStack: Created .agenticstackignore")
+
+    if api_key:
+        write_config("api_key", api_key)
+    if provider:
+        write_config("provider", provider)
+    if model:
+        write_config("model", model)
+
+    run(Path.cwd())
+
+
+@main.command()
+def update():
+    """Refresh AgenticStack.txt for this project."""
+    if not config_exists():
+        click.echo("AgenticStack: No config found. Run 'agenticstack init' first.")
+        return
+
+    run(Path.cwd())

agenticstack/config.py

@@ -0,0 +1,98 @@
+import configparser
+from pathlib import Path
+
+CONFIG_FILE = ".agenticstack.ini"
+SECTION = "agenticstack"
+
+DEFAULTS = {
+    "model": "default",
+    "api_key": "None",
+    "provider": "anthropic",
+    "language": "auto",
+    "output_file": "AgenticStack.txt",
+    "depth": "standard",
+}
+
+
+def get_config_path() -> Path:
+    return Path.cwd() / CONFIG_FILE
+
+
+def config_exists() -> bool:
+    return get_config_path().exists()
+
+
+def create_default_config() -> None:
+    config = configparser.ConfigParser()
+    config[SECTION] = DEFAULTS
+    with open(get_config_path(), "w") as f:
+        config.write(f)
+    _add_to_gitignore()
+
+
+def read_config() -> dict:
+    if not config_exists():
+        create_default_config()
+    config = configparser.ConfigParser()
+    config.read(get_config_path())
+    return dict(config[SECTION])
+
+
+def write_config(key: str, value: str) -> None:
+    config = configparser.ConfigParser()
+    config.read(get_config_path())
+    if SECTION not in config:
+        config[SECTION] = {}
+    config[SECTION][key] = value
+    with open(get_config_path(), "w") as f:
+        config.write(f)
+
+
+def _add_to_gitignore() -> None:
+    gitignore_path = Path.cwd() / ".gitignore"
+    entry = CONFIG_FILE
+
+    if gitignore_path.exists():
+        content = gitignore_path.read_text()
+        if entry not in content:
+            with open(gitignore_path, "a") as f:
+                f.write(f"\n{entry}\n")
+    else:
+        with open(gitignore_path, "w") as f:
+            f.write(f"{entry}\n")
+
+
+def create_default_ignore_file() -> None:
+    ignore_path = Path.cwd() / ".agenticstackignore"
+
+    if ignore_path.exists():
+        return
+
+    content = """# AgenticStack Ignore File
+            # Patterns follow Unix glob syntax — same as .gitignore
+
+            # Virtual environments
+            .venv
+            venv
+            env
+
+            # Test directories
+            test_project
+            tests
+
+            # Build artifacts
+            build
+            dist
+            *.egg-info
+
+            # Cache
+            __pycache__
+            *.pyc
+
+            # Migrations
+            **/migrations/**
+
+            # Node modules (for projects with frontend)
+            node_modules
+            """
+    ignore_path.write_text(content, encoding="utf-8")

agenticstack/core.py

@@ -0,0 +1,54 @@
+from pathlib import Path
+from .config import read_config
+from .analyzer.python import PythonAnalyzer
+from .formatter.static import StaticFormatter
+from .prompt import build_prompt
+from .writer import write_output
+
+def _run_ai_mode(
+    static_output: str,
+    api_key: str,
+    provider_name: str,
+    model: str
+) -> str:
+    try:
+        from .providers.factory import get_provider
+        provider = get_provider(provider_name, api_key, model)
+        prompt = build_prompt(static_output)
+        print("AgenticStack: Sending to LLM...")
+        response = provider.generate(prompt)
+        return response
+    except Exception as e:
+        print(f"AgenticStack: AI mode failed — {e}")
+        print("AgenticStack: Falling back to static output")
+        return static_output
+
+
+def run(root_path: Path = None) -> None:
+    if root_path is None:
+        root_path = Path.cwd()
+
+    print("AgenticStack: Analyzing codebase...")
+
+    config = read_config()
+
+    analyzer = PythonAnalyzer(root_path)
+    results = analyzer.analyze()
+
+    formatter = StaticFormatter(results, root_path)
+    static_output = formatter.format()
+
+    api_key = config.get("api_key", "None")
+    provider_name = config.get("provider", "anthropic")
+    model = config.get("model", "default")
+
+    if api_key and api_key != "None":
+        print(f"AgenticStack: AI mode — using {provider_name} ({model})")
+        final_output = _run_ai_mode(static_output, api_key, provider_name, model)
+    else:
+        print("AgenticStack: Static mode — no API key found")
+        final_output = static_output
+
+    output_file = config.get("output_file", "AgenticStack.txt")
+    write_output(final_output, Path(output_file))
+    print(f"AgenticStack: Done. Output written to {output_file}")

agenticstack/formatter/static.py

@@ -0,0 +1,68 @@
+from pathlib import Path
+from collections import defaultdict
+
+class StaticFormatter:
+
+    def __init__(self, results: dict, root_path: Path):
+        self.results = results
+        self.root_path = root_path
+        self.output = []
+
+    def _format_file_map(self) -> None:
+        self.output.append("=" * 60)
+        self.output.append("SECTION 1: WHERE THINGS LIVE")
+        self.output.append("=" * 60)
+
+        grouped = defaultdict(list)
+        for filepath, file_type in self.results["file_map"].items():
+            grouped[file_type].append(filepath)
+
+        for file_type, files in sorted(grouped.items()):
+            self.output.append(f"\n[{file_type.upper()}]")
+            for f in sorted(files):
+                self.output.append(f"  {f}")
+    
+    def _format_classes(self) -> None:
+        self.output.append("\n" + "=" * 60)
+        self.output.append("SECTION 2: CLASSES")
+        self.output.append("=" * 60)
+
+        grouped = defaultdict(list)
+        for cls in self.results["classes"]:
+            grouped[cls["type"]].append(cls)
+
+        for file_type, classes in sorted(grouped.items()):
+            self.output.append(f"\n[{file_type.upper()}]")
+            for cls in sorted(classes, key=lambda x: x["name"]):
+                self.output.append(f"  {cls['name']} -> {cls['file']} (line {cls['line']})")
+
+    
+    def _format_functions(self) -> None:
+        self.output.append("\n" + "=" * 60)
+        self.output.append("SECTION 3: FUNCTIONS")
+        self.output.append("=" * 60)
+
+        grouped = defaultdict(list)
+        for func in self.results["functions"]:
+            grouped[func["type"]].append(func)
+
+        for file_type, functions in sorted(grouped.items()):
+            self.output.append(f"\n[{file_type.upper()}]")
+            for func in sorted(functions, key=lambda x: x["name"]):
+                self.output.append(f"  {func['name']} -> {func['file']} (line {func['line']})")
+
+    def _format_errors(self) -> None:
+        if not self.results["errors"]:
+            return
+        self.output.append("\n" + "=" * 60)
+        self.output.append("SECTION 4: PARSE ERRORS")
+        self.output.append("=" * 60)
+        for error in self.results["errors"]:
+            self.output.append(f"  {error['file']}: {error['error']}")
+
+    def format(self) -> str:
+        self._format_file_map()
+        self._format_classes()
+        self._format_functions()
+        self._format_errors()
+        return "\n".join(self.output)

agenticstack/prompt.py

@@ -0,0 +1,73 @@
+PROMPT_TEMPLATE = """You are an expert software architect analyzing a codebase.
+
+You have been given a static analysis of a Python project below.
+Your job is to produce a structured AgenticStack.txt file that helps AI agents
+understand this codebase before making any changes.
+
+STATIC ANALYSIS INPUT:
+{static_analysis}
+
+Produce output with EXACTLY these five sections. Do not add extra sections.
+Do not use markdown. Use plain text only.
+
+============================================================
+SECTION 1: WHERE THINGS LIVE
+============================================================
+List every important file with its exact path and one line description.
+Group by type: MODELS, VIEWS, SERIALIZERS, SERVICES, TESTS, OTHER.
+Format:
+  filename.py -> what this file does in one line
+
+============================================================
+SECTION 2: CHANGE RULES
+============================================================
+Based on the files found, write rules that tell an agent WHEN to touch which file.
+Use this decision tree format for each change type:
+
+When adding a new [thing]:
+  Step 1: Always edit [file]
+  Step 2: If [condition] -> also edit [file]
+  Step 3: If [condition] -> also edit [file]
+
+Cover these change types if the relevant files exist in the project:
+- Adding a model field (always include migration step for Django projects)
+- Adding a new endpoint
+- Adding a new model
+- Adding business logic
+
+Every step must reference an actual file path from this project.
+Never write generic steps like "update the model file" — always write
+"edit test_project/app/models/user.py" using the real path.
+
+============================================================
+SECTION 3: FIELD EXPOSURE MAP
+============================================================
+List which models are exposed via API (have a serializer) vs internal only.
+Format:
+  ModelName -> EXPOSED (serializer: path/to/serializer.py)
+  ModelName -> INTERNAL (no serializer found)
+
+============================================================
+SECTION 4: HOW-TO GUIDES
+============================================================
+Write step by step guides using the ACTUAL file paths found in this project.
+Cover:
+- How to add a model field
+- How to add a new API endpoint
+
+Each step must reference a real file path from this codebase.
+Do not use generic placeholders like myapp/ or yourproject/.
+
+============================================================
+SECTION 5: AGENT NOTES
+============================================================
+Write 5 to 10 critical things an agent must know before editing this codebase.
+Focus on patterns, constraints, and things that break easily.
+Base these notes on what you can infer from the file structure and class names found.
+
+Be specific. Be direct. No filler text.
+"""
+
+
+def build_prompt(static_analysis: str) -> str:
+    return PROMPT_TEMPLATE.format(static_analysis=static_analysis)

agenticstack/providers/anthropic.py

@@ -0,0 +1,31 @@
+from .base import BaseProvider
+
+
+ANTHROPIC_MODELS = {
+    "default": "claude-sonnet-4-20250514",
+    "fast": "claude-haiku-4-5-20251001",
+    "smart": "claude-opus-4-20250514",
+}
+
+
+class AnthropicProvider(BaseProvider):
+
+    def __init__(self, api_key: str, model: str = "default"):
+        resolved_model = ANTHROPIC_MODELS.get(model, ANTHROPIC_MODELS["default"])
+        super().__init__(api_key, resolved_model)
+
+    def generate(self, prompt: str) -> str:
+        try:
+            import anthropic
+            client = anthropic.Anthropic(api_key=self.api_key)
+            message = client.messages.create(
+                model=self.model,
+                max_tokens=8096,
+                messages=[{"role": "user", "content": prompt}],
+            )
+            return message.content[0].text
+        except ImportError:
+            raise ImportError(
+                "Anthropic SDK not installed. "
+                "Run: pip install agenticstack[anthropic]"
+            )

agenticstack/providers/base.py

@@ -0,0 +1,12 @@
+from abc import ABC, abstractmethod
+
+
+class BaseProvider(ABC):
+
+    def __init__(self, api_key: str, model: str):
+        self.api_key = api_key
+        self.model = model
+
+    @abstractmethod
+    def generate(self, prompt: str) -> str:
+        pass

agenticstack/providers/factory.py

@@ -0,0 +1,21 @@
+from .anthropic import AnthropicProvider
+from .openai import OpenAIProvider
+from .base import BaseProvider
+
+
+PROVIDERS = {
+    "anthropic": AnthropicProvider,
+    "openai": OpenAIProvider,
+}
+
+
+def get_provider(provider: str, api_key: str, model: str) -> BaseProvider:
+    provider_class = PROVIDERS.get(provider.lower())
+
+    if provider_class is None:
+        raise ValueError(
+            f"Unknown provider '{provider}'. "
+            f"Valid options are: {', '.join(PROVIDERS.keys())}"
+        )
+
+    return provider_class(api_key=api_key, model=model)

agenticstack/providers/openai.py

@@ -0,0 +1,31 @@
+from .base import BaseProvider
+
+
+OPENAI_MODELS = {
+    "default": "gpt-4o",
+    "fast": "gpt-4o-mini",
+    "smart": "gpt-4o",
+}
+
+
+class OpenAIProvider(BaseProvider):
+
+    def __init__(self, api_key: str, model: str = "default"):
+        resolved_model = OPENAI_MODELS.get(model, OPENAI_MODELS["default"])
+        super().__init__(api_key, resolved_model)
+
+    def generate(self, prompt: str) -> str:
+        try:
+            import openai
+            client = openai.OpenAI(api_key=self.api_key)
+            response = client.chat.completions.create(
+                model=self.model,
+                max_tokens=8096,
+                messages=[{"role": "user", "content": prompt}],
+            )
+            return response.choices[0].message.content
+        except ImportError:
+            raise ImportError(
+                "OpenAI SDK not installed. "
+                "Run: pip install agenticstack[openai]"
+            )

agenticstack/writer.py

@@ -0,0 +1,5 @@
+from pathlib import Path
+
+
+def write_output(content: str, output_path: Path) -> None:
+    output_path.write_text(content, encoding="utf-8")

agenticstackfile-0.1.0.dist-info/METADATA

@@ -0,0 +1,15 @@
+Metadata-Version: 2.4
+Name: agenticstackfile
+Version: 0.1.0
+Summary: Instant codebase map for AI agents — understand any project before making changes
+Author-email: Rajat Handa <handarajat111@gmail.com>
+License-Expression: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.20.0; extra == "anthropic"
+Provides-Extra: openai
+Requires-Dist: openai>=1.0.0; extra == "openai"
+Provides-Extra: all
+Requires-Dist: anthropic>=0.20.0; extra == "all"
+Requires-Dist: openai>=1.0.0; extra == "all"

agenticstackfile-0.1.0.dist-info/RECORD

@@ -0,0 +1,22 @@
+agenticstack/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+agenticstack/cli.py,sha256=PRoXFZHFlEYdO8RZj-73cFCT4yxP-1a5XGnbd0eO_8k,1349
+agenticstack/config.py,sha256=AAOdDVyoVHYMiN2SZQs57C4pAkYlqAnGsroK2WOC1no,2282
+agenticstack/core.py,sha256=d7jNpoDYmLXpk7TEFOhwzASzS6DkiImf_WpKbVvgL0Q,1759
+agenticstack/errors.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+agenticstack/prompt.py,sha256=9sI2hmwZ_0WaSIzphITLFnjDSwNaRHCYIdvBT49y6AI,2917
+agenticstack/writer.py,sha256=LDeSxHb1w9b2iI7bpwfGD4BvBaIeoxhKwv_Fi3DKmH4,139
+agenticstack/analyzer/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+agenticstack/analyzer/base.py,sha256=BPep-mb2q-g0R9TSGPu2YPmwr7hDTD6swUH9KVUwGS4,229
+agenticstack/analyzer/python.py,sha256=VYWUYdv5vNYdRCFolzAWcGx45ioyipKczdlL4FS9N3o,4410
+agenticstack/formatter/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+agenticstack/formatter/static.py,sha256=MeJLrpZIaj2bEV9iYIjNr5ACQg2zQc6vUna-n8qVaXw,2472
+agenticstack/providers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+agenticstack/providers/anthropic.py,sha256=IY9GblE0yu8ano_n24XcVNE4ZzpNVtN2yZPUBOS6o-M,978
+agenticstack/providers/base.py,sha256=hAQEwZR-ZiLlNTeiowQNuKCdbVUP3vv7InnBRNG7QVo,249
+agenticstack/providers/factory.py,sha256=-0NlcrSJLL0wVDatjrVni9Zse_LMCMnrQhaTDgPUfPg,556
+agenticstack/providers/openai.py,sha256=rVdoTxWM0gOxkIaOwU-d_FlHi1SjhOIHhQBx2-FbHoY,924
+agenticstackfile-0.1.0.dist-info/METADATA,sha256=IwXiajKR01HPMjv4BbCvxBFAj6erSTo5EjKXMzRQn4Y,558
+agenticstackfile-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+agenticstackfile-0.1.0.dist-info/entry_points.txt,sha256=CXFHpk2Qkn3VUwf9Sjc_uQli06a9ZfIPAvwJhcufXJs,55
+agenticstackfile-0.1.0.dist-info/top_level.txt,sha256=yQdgfr5cjlysSInqzDO5E_8lpauYK2tFaYVxcBaX8C0,13
+agenticstackfile-0.1.0.dist-info/RECORD,,

agenticstackfile-0.1.0.dist-info/WHEEL

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

agenticstackfile-0.1.0.dist-info/entry_points.txt

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

agenticstackfile-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+agenticstack