pylennon 0.1.0__tar.gz

pylennon-0.1.0/.gitignore

@@ -0,0 +1,21 @@
+.idea
+.idea/*
+
+# Python bytecode
+__pycache__/
+*.py[cod]
+
+# Virtual environment
+.venv/
+
+# Build / distribution artifacts
+dist/
+*.egg-info/
+src/*.egg-info/
+
+# Secrets / env files
+.env
+*.env
+set_env.ps1
+/set_env_shit.ps1
+pylennon.log

pylennon-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026  Novoselskiy Maxim Igorevich
+
+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.

pylennon-0.1.0/PKG-INFO

@@ -0,0 +1,48 @@
+Metadata-Version: 2.4
+Name: pylennon
+Version: 0.1.0
+Summary: AI-assisted Python development: write interfaces, generate implementations
+Project-URL: Homepage, https://github.com/MaxNovoselsky/PyLennon
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: anthropic>=0.55
+Requires-Dist: libcst>=1.0
+Description-Content-Type: text/markdown
+
+# PyLennon
+
+AI-assisted Python development framework. Write function interfaces (signatures, type hints, docstrings); `pylennon build` generates the implementations using Claude.
+
+## Dev setup
+
+```powershell
+# Install uv (once)
+winget install astral-sh.uv
+
+# Clone, then:
+uv sync
+
+# Verify
+uv run pylennon --help
+uv run pylennon build example/stubs.py
+```
+
+## Usage
+
+```python
+from pylennon import LennonApp
+
+lennon_app = LennonApp()
+
+@lennon_app.imagine
+def parse_invoice(raw_text: str) -> Invoice:
+    """Parse a raw invoice string into a structured Invoice object."""
+    ...
+```
+
+```powershell
+pylennon build src/invoices.py
+```
+
+See `idea.md` for the full design.

pylennon-0.1.0/README.md

@@ -0,0 +1,36 @@
+# PyLennon
+
+AI-assisted Python development framework. Write function interfaces (signatures, type hints, docstrings); `pylennon build` generates the implementations using Claude.
+
+## Dev setup
+
+```powershell
+# Install uv (once)
+winget install astral-sh.uv
+
+# Clone, then:
+uv sync
+
+# Verify
+uv run pylennon --help
+uv run pylennon build example/stubs.py
+```
+
+## Usage
+
+```python
+from pylennon import LennonApp
+
+lennon_app = LennonApp()
+
+@lennon_app.imagine
+def parse_invoice(raw_text: str) -> Invoice:
+    """Parse a raw invoice string into a structured Invoice object."""
+    ...
+```
+
+```powershell
+pylennon build src/invoices.py
+```
+
+See `idea.md` for the full design.

pylennon-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pylennon"
+version = "0.1.0"
+description = "AI-assisted Python development: write interfaces, generate implementations"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+dependencies = [
+    "anthropic>=0.55",
+    "libcst>=1.0",
+]
+
+[project.scripts]
+pylennon = "pylennon.__main__:main"
+
+[project.urls]
+Homepage = "https://github.com/MaxNovoselsky/PyLennon"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pylennon"]
+
+[tool.hatch.build.targets.sdist]
+exclude = [
+    "example",
+    "idea.md",
+    "progress.md",
+    "functional_tests"
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+]

pylennon-0.1.0/src/pylennon/__init__.py

@@ -0,0 +1,9 @@
+import logging
+
+from .app import LennonApp
+from .exceptions import GenerationError, ImagineNotBuiltError
+from .stub import StubInfo
+
+logging.getLogger(__name__).addHandler(logging.NullHandler())
+
+__all__ = ["LennonApp", "StubInfo", "ImagineNotBuiltError", "GenerationError"]

pylennon-0.1.0/src/pylennon/__main__.py

@@ -0,0 +1,203 @@
+import argparse
+import json
+import shutil
+import sys
+from pathlib import Path
+
+
+def _load_apps(path: Path):
+    from .build import load_app_from_file, load_apps_from_dir
+    if path.is_dir():
+        apps = load_apps_from_dir(path)
+        if not apps:
+            print(f"error: no LennonApp instance found in {path}", file=sys.stderr)
+            sys.exit(1)
+        return apps
+    return [load_app_from_file(path)]
+
+
+def _rel(p: str) -> str:
+    try:
+        return str(Path(p).relative_to(Path.cwd()))
+    except ValueError:
+        return p
+
+
+def _read_manifest(app) -> list[dict]:
+    from .app import MANIFEST_FILE
+    manifest_path = app.output_dir / MANIFEST_FILE
+    try:
+        raw = json.loads(manifest_path.read_text(encoding="utf-8"))
+        return raw if isinstance(raw, list) else []
+    except (FileNotFoundError, json.JSONDecodeError):
+        return []
+
+
+def cmd_build(args):
+    from .build import build_app, load_app_from_file, load_apps_from_dir
+
+    path = Path(args.file).resolve()
+    if not path.exists():
+        print(f"error: path not found: {path}", file=sys.stderr)
+        sys.exit(1)
+
+    if path.is_dir():
+        apps = load_apps_from_dir(path)
+        if not apps:
+            print(f"error: no LennonApp instance found in {path}", file=sys.stderr)
+            sys.exit(1)
+        total_built = sum(build_app(app) for app in apps)
+        total_stubs = sum(len(app.stubs) for app in apps)
+        print(f"\nDone — built {total_built}/{total_stubs} stub(s)")
+    else:
+        app = load_app_from_file(path)
+        built = build_app(app, prune_orphans=False)
+        print(f"\nDone — built {built}/{len(app.stubs)} stub(s) in {app.output_dir}")
+
+
+def cmd_status(args):
+    path = Path(args.file).resolve()
+    if not path.exists():
+        print(f"error: path not found: {path}", file=sys.stderr)
+        sys.exit(1)
+
+    apps = _load_apps(path)
+
+    for app in apps:
+        built_hashes = {e["stub_hash"] for e in _read_manifest(app)}
+        stubs = app.all_stubs
+        if not stubs:
+            continue
+        name_w = max(len(s.name) for s in stubs)
+        for stub in stubs:
+            status = "built" if stub.stub_hash in built_hashes else "missing"
+            src = _rel(stub.source_file)
+            print(f"{status:<7}  {stub.stub_hash}  {stub.name:<{name_w}}  {src}")
+
+
+def cmd_detail(args):
+    from ._imagine import build_system_prompt, build_user_prompt
+    from .app import MANIFEST_FILE
+
+    path = Path(args.file).resolve()
+    if not path.exists():
+        print(f"error: path not found: {path}", file=sys.stderr)
+        sys.exit(1)
+
+    apps = _load_apps(path)
+
+    matches: list[tuple] = []  # (app, stub)
+    for app in apps:
+        for stub in app.all_stubs:
+            if stub.stub_hash == args.stub_hash:
+                matches.append((app, stub))
+
+    if not matches:
+        print(f"error: no stub with hash '{args.stub_hash}' found in {path}", file=sys.stderr)
+        sys.exit(1)
+
+    found_app, first_stub = matches[0]
+    manifest_entry = next(
+        (e for e in _read_manifest(found_app) if e.get("stub_hash") == args.stub_hash),
+        None,
+    )
+
+    status = "built" if manifest_entry else "missing"
+    print(f"name:         {first_stub.name}")
+    print(f"stub_hash:    {first_stub.stub_hash}")
+    print(f"status:       {status}")
+    if manifest_entry:
+        print(f"prompt_hash:  {manifest_entry['prompt_hash']}")
+        print(f"generated:    {manifest_entry['generated']}")
+    src_files = [_rel(s.source_file) for _, s in matches]
+    label = "source_file: " if len(src_files) == 1 else "source_files:"
+    print(f"{label}  {src_files[0]}")
+    for f in src_files[1:]:
+        print(f"               {f}")
+
+    system_prompt = build_system_prompt(
+        instructions_file=found_app.instructions_file,
+        always_include=found_app.always_include,
+    )
+    user_prompt = build_user_prompt(first_stub)
+
+    print()
+    print("--- SYSTEM PROMPT ---")
+    print(system_prompt, end="")
+    print()
+    print("--- USER PROMPT ---")
+    print(user_prompt, end="")
+
+
+def cmd_scaffold(args):
+    from .scaffold import scaffold
+
+    src_dir = Path(args.file).resolve()
+    if not src_dir.exists():
+        print(f"error: path not found: {src_dir}", file=sys.stderr)
+        sys.exit(1)
+    if not src_dir.is_dir():
+        print(f"error: scaffold requires a directory, not a file: {src_dir}", file=sys.stderr)
+        sys.exit(1)
+
+    out_dir = Path(args.output_dir).resolve()
+
+    apps = _load_apps(src_dir)
+    scaffolded, skipped, copied = scaffold(src_dir, out_dir, apps)
+
+    total = scaffolded + skipped + copied
+    print(f"\nDone -- {scaffolded} file(s) scaffolded, {skipped} skipped, {copied} copied -> {_rel(str(out_dir))}")
+
+
+def cmd_clean(args):
+    path = Path(args.file).resolve()
+    if not path.exists():
+        print(f"error: path not found: {path}", file=sys.stderr)
+        sys.exit(1)
+
+    apps = _load_apps(path)
+    deleted: set[Path] = set()
+    for app in apps:
+        out = app.output_dir.resolve()
+        if out in deleted:
+            continue
+        if out.exists():
+            print(f"Deleting {_rel(str(out))} ...")
+            shutil.rmtree(out)
+        else:
+            print(f"Nothing to clean — {_rel(str(out))} does not exist")
+        deleted.add(out)
+
+
+def main():
+    parser = argparse.ArgumentParser(prog="pylennon")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p = sub.add_parser("build", help="Generate implementations for all @imagine stubs")
+    p.add_argument("file", help="Path to the module or directory containing LennonApp stubs")
+    p.set_defaults(func=cmd_build)
+
+    p = sub.add_parser("status", help="Show build status of all registered stubs")
+    p.add_argument("file", help="Path to the module or directory containing LennonApp stubs")
+    p.set_defaults(func=cmd_status)
+
+    p = sub.add_parser("detail", help="Show full metadata and prompt for a specific stub")
+    p.add_argument("file", help="Path to the module or directory containing LennonApp stubs")
+    p.add_argument("stub_hash", help="The stub hash to inspect (from `pylennon status`)")
+    p.set_defaults(func=cmd_detail)
+
+    p = sub.add_parser("scaffold", help="Produce a standalone copy without pylennon dependency")
+    p.add_argument("file", help="Source directory containing LennonApp stubs")
+    p.add_argument("output_dir", help="Directory to write the scaffolded output")
+    p.set_defaults(func=cmd_scaffold)
+
+    p = sub.add_parser("clean", help="Delete the generated/ output directory")
+    p.add_argument("file", help="Path to the module or directory containing the LennonApp instance")
+    p.set_defaults(func=cmd_clean)
+
+    args = parser.parse_args()
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()

pylennon-0.1.0/src/pylennon/_imagine.py

@@ -0,0 +1,312 @@
+from __future__ import annotations
+
+import hashlib
+import inspect
+import json
+import logging
+import textwrap
+from pathlib import Path
+
+import anthropic
+from anthropic.types import ThinkingConfigDisabledParam, ToolChoiceNoneParam
+
+from .stub import StubInfo
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_MODEL = "claude-sonnet-4-6"
+
+DEFAULT_SYSTEM_PROMPT = """\
+You are part of PyLennon, an AI-assisted Python development framework.
+
+PyLennon allows developers to write stubs — Python functions and classes with \
+signatures, type hints, and docstrings, but with `...` as the body — decorated \
+with `@lennon_app.imagine`. At build time, PyLennon sends each stub to you to \
+generate a working implementation. At runtime, the `@imagine` decorator \
+transparently intercepts calls and routes them to the generated code.
+
+YOUR ROLE:
+  You receive one stub at a time and return a complete, working Python implementation.
+
+IMPORTANT — what @imagine stubs are:
+  - A function or class marked `@lennon_app.imagine` is NOT empty or unimplemented at runtime.
+  - It has a fully working AI-generated implementation that the framework loads automatically.
+  - Stubs always show `...` as the body — that is the contract, not the implementation.
+  - If you see a stub in `uses` or `context` with `...` as its body or method bodies,
+    do NOT implement it. It is already generated and works at runtime — treat it as a black box.
+
+IMPORTANT RULES:
+ - do **NOT** use any tools, like WebFetch. It's strictly forbidden.
+
+RESPONSE FORMAT:
+  - Respond with a JSON object containing a single key "code" whose value is
+    the complete, valid Python source file as a string — nothing else in "code".
+  - No prose, no markdown fences, no comments outside the code, no explanations.
+  - Preserve the exact function or class name and signature from the stub —
+    the framework dispatches calls by name, so renaming anything breaks runtime dispatch.
+
+IMPLEMENTATION RULES:
+  - Target Python 3.12.
+  - Implement exactly what the docstring describes — no more, no less.
+  - Do NOT add public methods, functions, or attributes not present in the stub.
+  - You MAY add private (`_name`) or name-mangled (`__name`) helpers if they simplify the implementation.
+  - Raise `ValueError` or `TypeError` for invalid inputs when the docstring specifies constraints.
+    Do not silently swallow errors or return sentinel values unless the stub explicitly says so.
+  - The output is a standalone module: no `if __name__ == '__main__'` blocks, no example usage, no test code.
+  - Do not add docstrings or type hints, PyLennon will add it from original function afterwards.
+  - If a stub method is shown decorated with `@property` (and, where present, `@<name>.setter` /
+    `@<name>.deleter`), implement it as a property in the generated class — do not turn it into a
+    plain method or a constructor-assigned attribute.
+
+CONTEXT (type definitions):
+  - The `context` section lists types referenced by the stub — dataclasses, Pydantic models, enums, etc.
+  - They are provided so you understand the shape of the data your function receives or returns:
+    field names, types, validators, and other constraints that affect how you interact with them.
+  - Import them using the exact paths shown — do not redefine or copy-paste them into your output.
+  - If a context type has `@lennon_app.imagine` on it, or its methods show `...` as the body,
+    it is an @imagine stub with a real generated implementation at runtime.
+    Do not implement it — just import and use it as-is.
+
+IMPORTS:
+  - Import only what you actually use.
+  - Use the exact import paths shown in the type context section.
+  - Prefer stdlib over third-party when both work equally well.
+
+USES:
+  - If `uses` functions or classes are provided, call them directly — do not reimplement their logic.
+  - They are shown with `...` as the body because they are @imagine stubs, but they have real,
+    working generated implementations at runtime. Do not implement them — just call them.\
+"""
+
+
+def _render_property(attr_name: str, prop: property, *, indent: str) -> str:
+    blocks: list[str] = []
+    for decorator, fn in (
+        ("@property", prop.fget),
+        (f"@{attr_name}.setter", prop.fset),
+        (f"@{attr_name}.deleter", prop.fdel),
+    ):
+        if fn is None:
+            continue
+        try:
+            sig = str(inspect.signature(fn))
+        except (ValueError, TypeError):
+            sig = "(self)" if fn is prop.fget else "(self, value)"
+        doc = inspect.getdoc(fn)
+        block = [f"{indent}{decorator}", f"{indent}def {attr_name}{sig}:"]
+        if doc:
+            block.append(f'{indent}    """{doc}"""')
+        block.append(f"{indent}    ...")
+        blocks.append("\n".join(block))
+    return "\n".join(blocks)
+
+
+def _get_class_context(stub: StubInfo) -> str | None:
+    qualname = getattr(stub.func, '__qualname__', '')
+    if '.' not in qualname:
+        return None
+    class_name = qualname.rsplit('.', 1)[0]
+    module = inspect.getmodule(stub.func)
+    if module is None:
+        return None
+    cls = getattr(module, class_name, None)
+    if cls is None or not inspect.isclass(cls):
+        return None
+
+    lines = [f"class {class_name}:"]
+    for attr_name, val in vars(cls).items():
+        if isinstance(val, property):
+            lines.append(_render_property(attr_name, val, indent="    "))
+            continue
+        if not callable(val) and not isinstance(val, (classmethod, staticmethod)):
+            continue
+        fn = val.__func__ if isinstance(val, (classmethod, staticmethod)) else val
+        if attr_name == '__init__':
+            try:
+                src = textwrap.dedent(inspect.getsource(fn))
+                lines.append(textwrap.indent(src, "    "))
+            except (OSError, TypeError):
+                try:
+                    sig = str(inspect.signature(fn))
+                except (ValueError, TypeError):
+                    sig = "(*args, **kwargs)"
+                lines.append(f"    def __init__{sig}: ...")
+        elif attr_name.startswith('__'):
+            continue
+        else:
+            try:
+                sig = str(inspect.signature(fn))
+            except (ValueError, TypeError):
+                sig = "(*args, **kwargs)"
+            doc = inspect.getdoc(fn)
+            lines.append(f"    def {attr_name}{sig}:")
+            if doc:
+                lines.append(f'        """{doc}"""')
+            lines.append("        ...")
+    return "\n".join(lines)
+
+
+def build_system_prompt(*, instructions_file: Path, always_include: list[Path]) -> str:
+    parts: list[str] = [DEFAULT_SYSTEM_PROMPT]
+
+    if instructions_file.exists():
+        parts.append("")
+        parts.append(instructions_file.read_text(encoding="utf-8").strip())
+
+    for extra in always_include:
+        if extra.exists():
+            parts.append("")
+            parts.append(extra.read_text(encoding="utf-8").strip())
+
+    return "\n".join(parts) + "\n"
+
+
+def build_user_prompt(stub: StubInfo) -> str:
+    parts: list[str] = []
+
+    class_ctx = _get_class_context(stub)
+
+    if class_ctx:
+        parts.append("This stub is a method. Generate a standalone function (do not wrap it in a class).")
+        parts.append("The `self` parameter refers to an instance of the class shown in context below.")
+        parts.append("")
+        parts.append("This method belongs to the following class (shown for reference):")
+        parts.append("```python")
+        parts.append(class_ctx)
+        parts.append("```")
+        parts.append("")
+
+    if stub.context:
+        parts.append("The following types are referenced in this stub (do NOT redefine them, import instead):")
+        for t in stub.context:
+            module = getattr(t, '__module__', None)
+            qualname = getattr(t, '__qualname__', t.__name__)
+            parts.append("```python")
+            if module and module != 'builtins':
+                parts.append(f"# import: from {module} import {qualname}")
+            try:
+                parts.append(inspect.getsource(t))
+            except (OSError, TypeError):
+                parts.append(f"# {t.__name__} (source unavailable)")
+            parts.append("```")
+        parts.append("")
+
+    if stub.uses:
+        parts.append(
+            "The following functions are available for this stub to call"
+            " (signatures and docstrings only — they have real implementations at runtime):"
+        )
+        for fn in stub.uses:
+            try:
+                sig = str(inspect.signature(fn))
+            except (ValueError, TypeError):
+                sig = "(*args, **kwargs)"
+            doc = inspect.getdoc(fn)
+            parts.append("```python")
+            parts.append(f"def {fn.__name__}{sig}:")
+            if doc:
+                parts.append(f'    """{doc}"""')
+            parts.append("    ...")
+            parts.append("```")
+            parts.append("")
+
+    parts.append("Stub to implement:")
+    if stub.is_class:
+        lines = [f"class {stub.name}:"]
+        if stub.docstring:
+            lines.append(f'    """{stub.docstring}"""')
+        has_methods = False
+        for attr_name, val in vars(stub.func).items():
+            if attr_name.startswith('__') and attr_name != '__init__':
+                continue
+            if isinstance(val, property):
+                lines.append(_render_property(attr_name, val, indent="    "))
+                has_methods = True
+                continue
+            fn = val.__func__ if isinstance(val, (classmethod, staticmethod)) else val
+            if not callable(fn):
+                continue
+            try:
+                sig = str(inspect.signature(fn))
+            except (ValueError, TypeError):
+                sig = "(*args, **kwargs)"
+            doc = inspect.getdoc(fn)
+            lines.append(f"    def {attr_name}{sig}:")
+            if doc:
+                lines.append(f'        """{doc}"""')
+            lines.append("        ...")
+            has_methods = True
+        if not has_methods:
+            lines.append("    ...")
+        parts.append("```python")
+        parts.append("\n".join(lines))
+        parts.append("```")
+    else:
+        sig = str(stub.signature) if stub.signature else "(*args, **kwargs)"
+        parts.append("```python")
+        parts.append(f"def {stub.name}{sig}:")
+        if stub.docstring:
+            parts.append(f'    """{stub.docstring}"""')
+        parts.append("    ...")
+        parts.append("```")
+
+    return "\n".join(parts) + "\n"
+
+
+def compute_prompt_hash(system_prompt: str, user_prompt: str) -> str:
+    combined = system_prompt + "\x00" + user_prompt
+    return hashlib.sha256(combined.encode()).hexdigest()[:8]
+
+
+def generate_from_prompt(system_prompt: str, user_prompt: str, model: str = DEFAULT_MODEL) -> str:
+    from .exceptions import GenerationError
+
+    client = anthropic.Anthropic()
+    message = client.messages.create(
+        model=model,
+        max_tokens=16384,
+        thinking=ThinkingConfigDisabledParam(type="disabled"),
+        system=system_prompt,
+        messages=[{"role": "user", "content": user_prompt}],
+        tool_choice=ToolChoiceNoneParam(type="none"),
+        tools=[],
+        output_config={
+            "format": {
+                "type": "json_schema",
+                "schema": {
+                    "type": "object",
+                    "properties": {
+                        "code": {"type": "string"},
+                    },
+                    "required": ["code"],
+                    "additionalProperties": False,
+                },
+            }
+        },
+    )
+    logger.debug("System prompt: %s", system_prompt)
+    logger.debug("User prompt: %s", user_prompt)
+    logger.debug("AI raw response: %s", message.model_dump_json())
+
+    if message.stop_reason == "tool_use":
+        tool_names = [b.name for b in message.content if b.type == "tool_use"]
+        raise GenerationError(
+            f"model attempted to use tools ({', '.join(tool_names)}) — "
+            "tool use is not supported; check your API key or model configuration"
+        )
+
+    text_blocks = [block.text for block in message.content if block.type == "text"]
+    if not text_blocks:
+        content_types = [b.type for b in message.content]
+        raise GenerationError(
+            f"model returned no text content (stop_reason={message.stop_reason!r}, "
+            f"content types: {content_types})"
+        )
+
+    try:
+        data = json.loads(text_blocks[0])
+        code: str = data["code"]
+    except (json.JSONDecodeError, KeyError) as exc:
+        raise GenerationError(f"model returned malformed JSON response: {exc}") from exc
+
+    return code if code.endswith("\n") else code + "\n"