py-okf 0.1.0__py3-none-any.whl

py_okf-0.1.0.dist-info/METADATA

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: py-okf
+Version: 0.1.0
+Summary: Python library for Open Knowledge Format (OKF) file generation and refresh
+Author-email: Prabhay Gupta <coolprabhay90@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/prabhay759/py-okf
+Project-URL: Repository, https://github.com/prabhay759/py-okf
+Project-URL: Issues, https://github.com/prabhay759/py-okf/issues
+Keywords: okf,documentation,ast,code-analysis,open-knowledge-format
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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 :: Documentation
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Provides-Extra: watch
+Requires-Dist: watchdog>=3.0; extra == "watch"
+Dynamic: license-file
+
+# py-okf
+
+A Python library for generating and managing [Open Knowledge Format (OKF)](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing) files from Python projects.
+
+OKF is a vendor-neutral markdown specification that lets AI agents and humans access curated knowledge without vendor lock-in — a directory of `.md` files with YAML frontmatter, one file per concept (module, class, API, dataset, etc.).
+
+`py-okf` analyzes your Python codebase using the `ast` module and generates an `.okf/` bundle of markdown files describing your project's concepts.
+
+## Installation
+
+```bash
+pip install py-okf
+```
+
+## CLI Usage
+
+```bash
+# Generate OKF files for a Python project
+okf generate /path/to/your/project
+
+# Refresh stale OKF files (only regenerates files where source changed)
+okf refresh /path/to/your/project
+
+# Validate OKF files against the spec
+okf validate /path/to/your/project
+
+# Custom output directory
+okf generate /path/to/your/project -o docs/okf
+
+# Include private (underscore-prefixed) symbols
+okf generate /path/to/your/project --include-private
+```
+
+## Python API
+
+```python
+from pyokf import analyze_project, generate_module_concepts, OKFBundle
+from pathlib import Path
+
+# Analyze a project
+modules = analyze_project(Path("./myproject"))
+
+# Generate OKF concepts
+bundle = OKFBundle(Path("./.okf"))
+bundle.ensure_directory()
+for module in modules:
+    concepts = generate_module_concepts(module)
+    bundle.write_all(concepts)
+
+# Load and validate an existing bundle
+bundle = OKFBundle(Path("./.okf")).load()
+errors = bundle.validate_directory()
+```
+
+## Generated Output
+
+Running `okf generate .` produces an `.okf/` directory with flat, dotted-name files:
+
+```
+.okf/
+├── mypackage.md                    # module concept
+├── mypackage.Connection.md         # class concept
+└── mypackage.query.md              # api concept (exported function)
+```
+
+Each file contains YAML frontmatter followed by a markdown description:
+
+```markdown
+---
+type: api
+title: mypackage.query
+description: Execute a SQL query against the active connection.
+resource: ./mypackage/__init__.py
+tags:
+- python
+- api
+timestamp: '2026-06-22T10:00:00Z'
+---
+
+# query
+
+Execute a SQL query against the active connection.
+
+## Signature
+
+    def query(sql: str, params: Optional[list[str]] = None) -> list[dict]
+
+## Parameters
+
+- **`sql`**: `str`
+- **`params`**: `Optional[list[str]]` *(default: `None`)*
+
+## Returns
+
+`list[dict]`
+```
+
+## Concept Types
+
+| Type | Description |
+|------|-------------|
+| `module` | A Python module file |
+| `class` | A class definition |
+| `function` | A top-level function |
+| `api` | A function listed in `__all__` (publicly exported) |
+
+## Requirements
+
+- Python 3.10+
+- PyYAML >= 6.0

py_okf-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+py_okf-0.1.0.dist-info/licenses/LICENSE,sha256=3fs40A9lisNCJwF8fzRl0_HdX_n2gnpxaP_oYczkh3k,1070
+pyokf/__init__.py,sha256=3SMMhG96jtNIXne0KLoxStVPHhVMCMGaExgVsKSq_s8,711
+pyokf/analyzer.py,sha256=7vQcD2cc_H9H9SwQ7ak1vls0_Ewbm4vgX08ELlSuwDY,7357
+pyokf/bundle.py,sha256=ntLbIGKSzOlO8t6HHf38VGFR-LXDXcO6gCtoX-JXAi0,6148
+pyokf/cli.py,sha256=Eli82nPVRGOPD4r-u-7-8wHDSmGBFWmdOu6WmBGFHFk,4704
+pyokf/generator.py,sha256=3bQcfoZDNjdfgcFvBYZR1aYfPZ7HWwtbpM0C1mwSz30,7125
+pyokf/models.py,sha256=Tjs3WvX51UgkMkbq9sB8xzYiN3d8kBs91UJc7yqnSAs,3557
+py_okf-0.1.0.dist-info/METADATA,sha256=Bag1ubPuNmDH781vK25KzTIDZCHemIAichIPco-gUgE,4152
+py_okf-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+py_okf-0.1.0.dist-info/entry_points.txt,sha256=t8mt3EctJn9QyNy9TvrVnAvHM-R2HoRjOrN77yiiQMI,39
+py_okf-0.1.0.dist-info/top_level.txt,sha256=XavKik6EGlWF-hSXxAQ0j5LS4kpi_DG91n4BIOrNeYU,6
+py_okf-0.1.0.dist-info/RECORD,,

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

py_okf-0.1.0.dist-info/entry_points.txt

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

py_okf-0.1.0.dist-info/licenses/LICENSE

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

py_okf-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pyokf

pyokf/__init__.py

@@ -0,0 +1,33 @@
+"""py-okf: Python library for Open Knowledge Format (OKF) file generation."""
+
+__version__ = "0.1.0"
+
+from pyokf.models import (
+    ConceptType,
+    OKFConcept,
+    ArgumentInfo,
+    AttributeInfo,
+    MethodInfo,
+    ClassInfo,
+    FunctionInfo,
+    ModuleInfo,
+)
+from pyokf.analyzer import analyze_file, analyze_project
+from pyokf.generator import generate_concept, generate_module_concepts
+from pyokf.bundle import OKFBundle
+
+__all__ = [
+    "ConceptType",
+    "OKFConcept",
+    "ArgumentInfo",
+    "AttributeInfo",
+    "MethodInfo",
+    "ClassInfo",
+    "FunctionInfo",
+    "ModuleInfo",
+    "analyze_file",
+    "analyze_project",
+    "generate_concept",
+    "generate_module_concepts",
+    "OKFBundle",
+]

pyokf/analyzer.py

@@ -0,0 +1,213 @@
+"""Python AST analyzer for py-okf."""
+
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+from typing import Optional
+
+from pyokf.models import (
+    ArgumentInfo,
+    AttributeInfo,
+    ClassInfo,
+    FunctionInfo,
+    MethodInfo,
+    ModuleInfo,
+)
+
+_EXCLUDE_DIRS = frozenset({
+    ".git", "__pycache__", ".tox", "build", "dist", ".eggs",
+    "venv", ".venv", "env", ".env", "node_modules",
+    ".mypy_cache", ".pytest_cache", ".ruff_cache", ".okf",
+})
+
+
+def _extract_args(args: ast.arguments) -> list[ArgumentInfo]:
+    result: list[ArgumentInfo] = []
+
+    n_args = len(args.posonlyargs) + len(args.args)
+    n_defaults = len(args.defaults)
+    default_offset = n_args - n_defaults
+
+    all_positional = args.posonlyargs + args.args
+    for i, arg in enumerate(all_positional):
+        default_idx = i - default_offset
+        default = ast.unparse(args.defaults[default_idx]) if default_idx >= 0 else None
+        annotation = ast.unparse(arg.annotation) if arg.annotation else None
+        kind = "positional_only" if i < len(args.posonlyargs) else "positional"
+        result.append(ArgumentInfo(name=arg.arg, annotation=annotation, default=default, kind=kind))
+
+    if args.vararg:
+        ann = ast.unparse(args.vararg.annotation) if args.vararg.annotation else None
+        result.append(ArgumentInfo(name=args.vararg.arg, annotation=ann, kind="var_positional"))
+
+    for i, arg in enumerate(args.kwonlyargs):
+        kw_default = args.kw_defaults[i]
+        default = ast.unparse(kw_default) if kw_default is not None else None
+        ann = ast.unparse(arg.annotation) if arg.annotation else None
+        result.append(ArgumentInfo(name=arg.arg, annotation=ann, default=default, kind="keyword_only"))
+
+    if args.kwarg:
+        ann = ast.unparse(args.kwarg.annotation) if args.kwarg.annotation else None
+        result.append(ArgumentInfo(name=args.kwarg.arg, annotation=ann, kind="var_keyword"))
+
+    return result
+
+
+def _build_signature(func_node: ast.FunctionDef | ast.AsyncFunctionDef) -> str:
+    unparsed = ast.unparse(func_node)
+    first_line = unparsed.split("\n")[0]
+    return first_line.rstrip(":")
+
+
+def _extract_method(node: ast.FunctionDef | ast.AsyncFunctionDef) -> MethodInfo:
+    return MethodInfo(
+        name=node.name,
+        signature=_build_signature(node),
+        docstring=ast.get_docstring(node),
+        decorators=[ast.unparse(d) for d in node.decorator_list],
+        is_async=isinstance(node, ast.AsyncFunctionDef),
+        args=_extract_args(node.args),
+        returns=ast.unparse(node.returns) if node.returns else None,
+        line_number=node.lineno,
+    )
+
+
+def _extract_class(node: ast.ClassDef, module_name: str, source_file: str) -> ClassInfo:
+    attributes: list[AttributeInfo] = []
+    methods: list[MethodInfo] = []
+
+    for item in node.body:
+        if isinstance(item, ast.AnnAssign) and isinstance(item.target, ast.Name):
+            attributes.append(AttributeInfo(
+                name=item.target.id,
+                annotation=ast.unparse(item.annotation) if item.annotation else None,
+                default=ast.unparse(item.value) if item.value else None,
+            ))
+        elif isinstance(item, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            methods.append(_extract_method(item))
+
+    return ClassInfo(
+        name=node.name,
+        module_name=module_name,
+        source_file=source_file,
+        docstring=ast.get_docstring(node),
+        bases=[ast.unparse(b) for b in node.bases],
+        attributes=attributes,
+        methods=methods,
+        decorators=[ast.unparse(d) for d in node.decorator_list],
+        line_number=node.lineno,
+    )
+
+
+def _extract_function(
+    node: ast.FunctionDef | ast.AsyncFunctionDef,
+    module_name: str,
+    source_file: str,
+    exports: list[str],
+) -> FunctionInfo:
+    return FunctionInfo(
+        name=node.name,
+        module_name=module_name,
+        source_file=source_file,
+        signature=_build_signature(node),
+        docstring=ast.get_docstring(node),
+        decorators=[ast.unparse(d) for d in node.decorator_list],
+        is_async=isinstance(node, ast.AsyncFunctionDef),
+        args=_extract_args(node.args),
+        returns=ast.unparse(node.returns) if node.returns else None,
+        is_exported=node.name in exports,
+        line_number=node.lineno,
+    )
+
+
+def _extract_exports(tree: ast.Module) -> list[str]:
+    for node in tree.body:
+        if (
+            isinstance(node, ast.Assign)
+            and len(node.targets) == 1
+            and isinstance(node.targets[0], ast.Name)
+            and node.targets[0].id == "__all__"
+            and isinstance(node.value, (ast.List, ast.Tuple))
+        ):
+            return [
+                elt.s for elt in node.value.elts
+                if isinstance(elt, ast.Constant) and isinstance(elt.s, str)
+            ]
+    return []
+
+
+def _path_to_module_name(py_file: Path, package_root: Path) -> str:
+    rel = py_file.relative_to(package_root)
+    parts = list(rel.with_suffix("").parts)
+    if parts and parts[-1] == "__init__":
+        parts = parts[:-1]
+    return ".".join(parts) if parts else package_root.name
+
+
+def analyze_file(
+    py_file: Path,
+    module_name: Optional[str] = None,
+    package_root: Optional[Path] = None,
+) -> ModuleInfo:
+    """Analyze a single Python file and return a ModuleInfo."""
+    py_file = Path(py_file).resolve()
+    if package_root is None:
+        package_root = py_file.parent
+    else:
+        package_root = Path(package_root).resolve()
+
+    source = py_file.read_text(encoding="utf-8")
+    tree = ast.parse(source, filename=str(py_file))
+
+    if module_name is None:
+        module_name = _path_to_module_name(py_file, package_root)
+
+    source_file = str(py_file.relative_to(package_root))
+    exports = _extract_exports(tree)
+    classes: list[ClassInfo] = []
+    functions: list[FunctionInfo] = []
+
+    for node in tree.body:
+        if isinstance(node, ast.ClassDef):
+            classes.append(_extract_class(node, module_name, source_file))
+        elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            functions.append(_extract_function(node, module_name, source_file, exports))
+
+    return ModuleInfo(
+        name=module_name,
+        source_file=source_file,
+        docstring=ast.get_docstring(tree),
+        classes=classes,
+        functions=functions,
+        exports=exports,
+    )
+
+
+def analyze_project(
+    project_root: Path,
+    include_private: bool = False,
+) -> list[ModuleInfo]:
+    """Walk a Python project and analyze all .py files."""
+    project_root = Path(project_root).resolve()
+
+    src_dir = project_root / "src"
+    has_src_layout = src_dir.is_dir()
+
+    modules: list[ModuleInfo] = []
+    for py_file in sorted(project_root.rglob("*.py")):
+        if any(part in _EXCLUDE_DIRS for part in py_file.parts):
+            continue
+        if not include_private and py_file.name.startswith("_") and py_file.name != "__init__.py":
+            continue
+        # Use src/ as root for files inside it; project root for everything else
+        if has_src_layout and py_file.is_relative_to(src_dir):
+            package_root = src_dir
+        else:
+            package_root = project_root
+        try:
+            modules.append(analyze_file(py_file, package_root=package_root))
+        except SyntaxError:
+            pass
+
+    return modules

pyokf/bundle.py

@@ -0,0 +1,165 @@
+"""OKF bundle reader, writer, and validator."""
+
+from __future__ import annotations
+
+import datetime
+from pathlib import Path
+
+import yaml
+
+from pyokf.models import ConceptType, OKFConcept
+
+REQUIRED_FRONTMATTER = frozenset({"type", "title", "description", "resource", "timestamp"})
+VALID_TYPES = frozenset({t.value for t in ConceptType} | {
+    "dataset", "metric", "playbook", "runbook", "table",
+})
+
+
+class ValidationError(Exception):
+    """Raised when an OKF file fails validation."""
+
+
+class OKFBundle:
+    """Represents an OKF bundle directory (.okf/)."""
+
+    def __init__(self, directory: Path) -> None:
+        self.directory = Path(directory)
+        self._concepts: dict[str, OKFConcept] = {}
+
+    def load(self) -> "OKFBundle":
+        """Load all .md files from the bundle directory."""
+        if not self.directory.exists():
+            return self
+        for md_file in sorted(self.directory.glob("**/*.md")):
+            try:
+                concept = self._parse_file(md_file)
+                rel = str(md_file.relative_to(self.directory))
+                self._concepts[rel] = concept
+            except (ValueError, yaml.YAMLError):
+                pass
+        return self
+
+    def _parse_file(self, md_file: Path) -> OKFConcept:
+        content = md_file.read_text(encoding="utf-8")
+        if not content.startswith("---"):
+            raise ValueError(f"Missing frontmatter in {md_file}")
+        parts = content.split("---", 2)
+        if len(parts) < 3:
+            raise ValueError(f"Malformed frontmatter in {md_file}")
+        fm = yaml.safe_load(parts[1])
+        if not isinstance(fm, dict):
+            raise ValueError(f"Frontmatter is not a mapping in {md_file}")
+        body = parts[2].strip()
+
+        raw_ts = fm.get("timestamp")
+        if isinstance(raw_ts, datetime.datetime):
+            ts = raw_ts
+            if ts.tzinfo is None:
+                ts = ts.replace(tzinfo=datetime.timezone.utc)
+        elif isinstance(raw_ts, str):
+            ts = datetime.datetime.fromisoformat(raw_ts.replace("Z", "+00:00"))
+        else:
+            ts = datetime.datetime.now(tz=datetime.timezone.utc)
+
+        raw_type = fm.get("type", "function")
+        try:
+            concept_type = ConceptType(raw_type)
+        except ValueError:
+            concept_type = ConceptType.FUNCTION
+
+        known = {"type", "title", "description", "resource", "tags", "timestamp"}
+        extra = {k: v for k, v in fm.items() if k not in known}
+
+        return OKFConcept(
+            type=concept_type,
+            title=fm.get("title", ""),
+            description=fm.get("description", ""),
+            resource=fm.get("resource", ""),
+            output_path=str(md_file.relative_to(self.directory)),
+            tags=fm.get("tags", []),
+            timestamp=ts,
+            content=body,
+            extra_frontmatter=extra,
+        )
+
+    def write(self, concept: OKFConcept, overwrite: bool = True) -> Path:
+        """Write one OKFConcept to disk. Returns the path written to."""
+        from pyokf.generator import generate_concept
+
+        out_path = self.directory / concept.output_path
+        out_path.parent.mkdir(parents=True, exist_ok=True)
+
+        if not overwrite and out_path.exists():
+            return out_path
+
+        out_path.write_text(generate_concept(concept), encoding="utf-8")
+        self._concepts[concept.output_path] = concept
+        return out_path
+
+    def write_all(self, concepts: list[OKFConcept], overwrite: bool = True) -> list[Path]:
+        """Write multiple concepts, returning paths written."""
+        return [self.write(c, overwrite=overwrite) for c in concepts]
+
+    def needs_refresh(self, concept: OKFConcept, source_mtime: float) -> bool:
+        """Return True if the source file is newer than the existing OKF concept timestamp."""
+        existing = self._concepts.get(concept.output_path)
+        if existing is None:
+            return True
+        ts = existing.timestamp
+        if ts.tzinfo is None:
+            ts = ts.replace(tzinfo=datetime.timezone.utc)
+        source_dt = datetime.datetime.fromtimestamp(source_mtime, tz=datetime.timezone.utc)
+        return source_dt > ts
+
+    def validate_file(self, md_file: Path) -> list[str]:
+        """Validate a single .md file against the OKF spec. Returns list of error strings."""
+        errors: list[str] = []
+        try:
+            content = md_file.read_text(encoding="utf-8")
+        except OSError as e:
+            return [f"{md_file}: Cannot read file: {e}"]
+
+        if not content.startswith("---"):
+            return [f"{md_file}: Missing YAML frontmatter (file must start with ---)"]
+
+        parts = content.split("---", 2)
+        if len(parts) < 3:
+            return [f"{md_file}: Malformed frontmatter (missing closing ---)"]
+
+        try:
+            fm = yaml.safe_load(parts[1])
+        except yaml.YAMLError as e:
+            return [f"{md_file}: Invalid YAML: {e}"]
+
+        if not isinstance(fm, dict):
+            return [f"{md_file}: Frontmatter must be a YAML mapping"]
+
+        for field in sorted(REQUIRED_FRONTMATTER - set(fm.keys())):
+            errors.append(f"{md_file}: Missing required field '{field}'")
+
+        if "type" in fm and fm["type"] not in VALID_TYPES:
+            errors.append(
+                f"{md_file}: Invalid type '{fm['type']}'. "
+                f"Must be one of: {sorted(VALID_TYPES)}"
+            )
+
+        return errors
+
+    def validate_directory(self) -> dict[str, list[str]]:
+        """Validate all .md files in the bundle directory. Returns filepath -> errors dict."""
+        results: dict[str, list[str]] = {}
+        if not self.directory.exists():
+            return results
+        for md_file in sorted(self.directory.glob("**/*.md")):
+            errs = self.validate_file(md_file)
+            if errs:
+                results[str(md_file)] = errs
+        return results
+
+    @property
+    def concepts(self) -> list[OKFConcept]:
+        return list(self._concepts.values())
+
+    def ensure_directory(self) -> None:
+        """Create the bundle directory if it does not exist."""
+        self.directory.mkdir(parents=True, exist_ok=True)

pyokf/cli.py

@@ -0,0 +1,146 @@
+"""CLI entry point for py-okf."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from pyokf.analyzer import analyze_project
+from pyokf.bundle import OKFBundle
+from pyokf.generator import generate_module_concepts
+
+
+def _add_common_args(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("path", metavar="PATH", help="Path to the Python project root")
+    parser.add_argument(
+        "-o", "--output",
+        default=".okf",
+        metavar="DIR",
+        help="Output directory for OKF files (default: .okf)",
+    )
+
+
+def cmd_generate(args: argparse.Namespace) -> int:
+    project_root = Path(args.path).resolve()
+    if not project_root.exists():
+        print(f"error: path does not exist: {project_root}", file=sys.stderr)
+        return 1
+
+    okf_dir = (project_root / args.output).resolve()
+    bundle = OKFBundle(okf_dir)
+    bundle.ensure_directory()
+
+    include_private = getattr(args, "include_private", False)
+    modules = analyze_project(project_root, include_private=include_private)
+
+    if not modules:
+        print(f"No Python files found in: {project_root}")
+        return 0
+
+    total = 0
+    for module in modules:
+        concepts = generate_module_concepts(module, include_private=include_private)
+        paths = bundle.write_all(concepts)
+        for p in paths:
+            print(f"  generated: {p.relative_to(project_root)}")
+        total += len(paths)
+
+    print(f"\nGenerated {total} OKF file(s) in {okf_dir.relative_to(project_root)}/")
+    return 0
+
+
+def cmd_refresh(args: argparse.Namespace) -> int:
+    project_root = Path(args.path).resolve()
+    if not project_root.exists():
+        print(f"error: path does not exist: {project_root}", file=sys.stderr)
+        return 1
+
+    okf_dir = (project_root / args.output).resolve()
+    bundle = OKFBundle(okf_dir).load()
+
+    include_private = getattr(args, "include_private", False)
+    modules = analyze_project(project_root, include_private=include_private)
+
+    refreshed = 0
+    skipped = 0
+    for module in modules:
+        source_mtime = (project_root / module.source_file).stat().st_mtime
+        concepts = generate_module_concepts(module, include_private=include_private)
+        for concept in concepts:
+            if bundle.needs_refresh(concept, source_mtime):
+                bundle.write(concept, overwrite=True)
+                print(f"  refreshed: {concept.output_path}")
+                refreshed += 1
+            else:
+                skipped += 1
+
+    print(f"\nRefreshed {refreshed}, skipped {skipped} (up-to-date) OKF file(s).")
+    return 0
+
+
+def cmd_validate(args: argparse.Namespace) -> int:
+    project_root = Path(args.path).resolve()
+    okf_dir = (project_root / args.output).resolve()
+
+    if not okf_dir.exists():
+        print(f"error: OKF directory does not exist: {okf_dir}", file=sys.stderr)
+        return 1
+
+    bundle = OKFBundle(okf_dir)
+    results = bundle.validate_directory()
+
+    if not results:
+        total = len(list(okf_dir.glob("**/*.md")))
+        print(f"All {total} OKF file(s) are valid.")
+        return 0
+
+    total_errors = 0
+    for errors in results.values():
+        for err in errors:
+            print(f"  {err}", file=sys.stderr)
+            total_errors += 1
+
+    print(f"\n{total_errors} validation error(s) found.", file=sys.stderr)
+    return 1
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="okf",
+        description="py-okf: Generate and manage Open Knowledge Format (OKF) files for Python projects.",
+    )
+    parser.add_argument("--version", action="version", version="%(prog)s 0.1.0")
+
+    subparsers = parser.add_subparsers(dest="command", metavar="COMMAND")
+    subparsers.required = True
+
+    gen_parser = subparsers.add_parser("generate", help="Generate OKF files from Python source")
+    _add_common_args(gen_parser)
+    gen_parser.add_argument(
+        "--include-private",
+        action="store_true",
+        help="Include private (underscore-prefixed) symbols",
+    )
+    gen_parser.set_defaults(func=cmd_generate)
+
+    ref_parser = subparsers.add_parser("refresh", help="Refresh stale OKF files")
+    _add_common_args(ref_parser)
+    ref_parser.add_argument("--include-private", action="store_true")
+    ref_parser.set_defaults(func=cmd_refresh)
+
+    val_parser = subparsers.add_parser("validate", help="Validate OKF files against the spec")
+    _add_common_args(val_parser)
+    val_parser.set_defaults(func=cmd_validate)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    sys.exit(args.func(args))
+
+
+if __name__ == "__main__":
+    main()

pyokf/generator.py

@@ -0,0 +1,214 @@
+"""OKF concept generator — converts analysis results to OKFConcept objects."""
+
+from __future__ import annotations
+
+import datetime
+from typing import Optional
+
+import yaml
+
+from pyokf.models import (
+    ClassInfo,
+    ConceptType,
+    FunctionInfo,
+    MethodInfo,
+    ModuleInfo,
+    OKFConcept,
+)
+
+
+def _now_utc() -> datetime.datetime:
+    return datetime.datetime.now(tz=datetime.timezone.utc)
+
+
+def _okf_output_path(module_name: str, suffix: str = "") -> str:
+    name = f"{module_name}.{suffix}" if suffix else module_name
+    return f"{name}.md"
+
+
+def _render_method_section(method: MethodInfo) -> str:
+    prefix = "async " if method.is_async else ""
+    lines = [f"### `{prefix}{method.signature}`"]
+    if method.docstring:
+        lines += ["", method.docstring]
+    if method.decorators:
+        lines += ["", f"**Decorators:** {', '.join(f'`@{d}`' for d in method.decorators)}"]
+    return "\n".join(lines)
+
+
+def generate_module_concept(module: ModuleInfo) -> OKFConcept:
+    """Generate the OKF concept for the module-level file."""
+    description = module.docstring or f"Python module: {module.name}"
+
+    lines = [f"# {module.name}", ""]
+    if module.docstring:
+        lines += [module.docstring, ""]
+
+    if module.classes:
+        lines += ["## Classes", ""]
+        for cls in module.classes:
+            cls_path = _okf_output_path(module.name, cls.name)
+            desc = f" — {cls.docstring.split(chr(10))[0]}" if cls.docstring else ""
+            lines.append(f"- [`{cls.name}`]({cls_path}){desc}")
+        lines.append("")
+
+    pub_funcs = module.public_functions
+    if pub_funcs:
+        lines += ["## Functions", ""]
+        for fn in pub_funcs:
+            prefix = "async " if fn.is_async else ""
+            exported_badge = " _(exported)_" if fn.is_exported else ""
+            lines.append(f"- `{prefix}{fn.signature}`{exported_badge}")
+            if fn.docstring:
+                short_doc = fn.docstring.split("\n")[0]
+                lines.append(f"  {short_doc}")
+        lines.append("")
+
+    return OKFConcept(
+        type=ConceptType.MODULE,
+        title=module.name,
+        description=description,
+        resource=f"./{module.source_file}",
+        output_path=_okf_output_path(module.name),
+        tags=["python", "module"],
+        timestamp=_now_utc(),
+        content="\n".join(lines),
+    )
+
+
+def generate_class_concept(cls: ClassInfo) -> OKFConcept:
+    """Generate the OKF concept for a class."""
+    description = cls.docstring or f"Python class: {cls.name}"
+
+    lines = [f"# {cls.name}", ""]
+    if cls.bases:
+        lines += [f"**Inherits from:** {', '.join(f'`{b}`' for b in cls.bases)}", ""]
+    if cls.decorators:
+        lines += [f"**Decorators:** {', '.join(f'`@{d}`' for d in cls.decorators)}", ""]
+    if cls.docstring:
+        lines += [cls.docstring, ""]
+
+    if cls.attributes:
+        lines += ["## Attributes", ""]
+        for attr in cls.attributes:
+            ann = f": {attr.annotation}" if attr.annotation else ""
+            default = f" = {attr.default}" if attr.default is not None else ""
+            lines.append(f"- `{attr.name}{ann}{default}`")
+        lines.append("")
+
+    init = next((m for m in cls.methods if m.name == "__init__"), None)
+    if init:
+        lines += ["## Constructor", "", _render_method_section(init), ""]
+
+    public_non_init = [m for m in cls.public_methods if m.name != "__init__"]
+    if public_non_init:
+        lines += ["## Methods", ""]
+        for method in public_non_init:
+            lines += [_render_method_section(method), ""]
+
+    dunder_non_init = [m for m in cls.dunder_methods if m.name != "__init__"]
+    if dunder_non_init:
+        lines += ["## Special Methods", ""]
+        for method in dunder_non_init:
+            lines += [_render_method_section(method), ""]
+
+    return OKFConcept(
+        type=ConceptType.CLASS,
+        title=f"{cls.module_name}.{cls.name}",
+        description=description,
+        resource=f"./{cls.source_file}",
+        output_path=_okf_output_path(cls.module_name, cls.name),
+        tags=["python", "class"],
+        timestamp=_now_utc(),
+        content="\n".join(lines),
+    )
+
+
+def generate_function_concept(fn: FunctionInfo) -> OKFConcept:
+    """Generate the OKF concept for a top-level function."""
+    description = fn.docstring or f"Python function: {fn.name}"
+    concept_type = fn.concept_type
+
+    prefix = "async " if fn.is_async else ""
+    lines = [f"# {fn.name}", ""]
+    if fn.docstring:
+        lines += [fn.docstring, ""]
+
+    lines += ["## Signature", "", "```python", f"{prefix}{fn.signature}", "```", ""]
+
+    if fn.args:
+        lines += ["## Parameters", ""]
+        for arg in fn.args:
+            ann = f": `{arg.annotation}`" if arg.annotation else ""
+            default = f" *(default: `{arg.default}`)*" if arg.default is not None else ""
+            kind_note = ""
+            if arg.kind == "keyword_only":
+                kind_note = " *(keyword-only)*"
+            elif arg.kind == "var_positional":
+                kind_note = " *(variadic)*"
+            elif arg.kind == "var_keyword":
+                kind_note = " *(keyword variadic)*"
+            lines.append(f"- **`{arg.name}`**{ann}{default}{kind_note}")
+        lines.append("")
+
+    if fn.returns:
+        lines += ["## Returns", "", f"`{fn.returns}`", ""]
+
+    if fn.decorators:
+        lines += ["## Decorators", ""]
+        for d in fn.decorators:
+            lines.append(f"- `@{d}`")
+        lines.append("")
+
+    return OKFConcept(
+        type=concept_type,
+        title=f"{fn.module_name}.{fn.name}",
+        description=description,
+        resource=f"./{fn.source_file}",
+        output_path=_okf_output_path(fn.module_name, fn.name),
+        tags=["python", concept_type.value],
+        timestamp=_now_utc(),
+        content="\n".join(lines),
+    )
+
+
+def generate_module_concepts(
+    module: ModuleInfo,
+    include_private: bool = False,
+    generate_functions: bool = True,
+    generate_classes: bool = True,
+) -> list[OKFConcept]:
+    """Generate all OKF concepts for a module and its contents."""
+    concepts: list[OKFConcept] = [generate_module_concept(module)]
+
+    if generate_classes:
+        for cls in module.classes:
+            concepts.append(generate_class_concept(cls))
+
+    if generate_functions:
+        for fn in module.functions:
+            if include_private or fn.is_public:
+                concepts.append(generate_function_concept(fn))
+
+    return concepts
+
+
+def generate_concept(concept: OKFConcept) -> str:
+    """Render an OKFConcept to its full markdown string (frontmatter + body)."""
+    frontmatter: dict = {
+        "type": concept.type.value,
+        "title": concept.title,
+        "description": concept.description,
+        "resource": concept.resource,
+        "tags": concept.tags,
+        "timestamp": concept.timestamp.strftime("%Y-%m-%dT%H:%M:%SZ"),
+    }
+    frontmatter.update(concept.extra_frontmatter)
+
+    fm_str = yaml.dump(
+        frontmatter,
+        default_flow_style=False,
+        allow_unicode=True,
+        sort_keys=False,
+    )
+    return f"---\n{fm_str}---\n\n{concept.content.strip()}\n"

pyokf/models.py

@@ -0,0 +1,131 @@
+"""Data models for py-okf."""
+
+from __future__ import annotations
+
+import datetime
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Optional
+
+
+class ConceptType(Enum):
+    """Supported OKF concept types for Python constructs."""
+    MODULE = "module"
+    CLASS = "class"
+    FUNCTION = "function"
+    API = "api"
+
+
+@dataclass
+class OKFConcept:
+    """Represents one OKF file (one markdown file with YAML frontmatter)."""
+    type: ConceptType
+    title: str
+    description: str
+    resource: str
+    output_path: str
+    tags: list[str] = field(default_factory=list)
+    timestamp: datetime.datetime = field(
+        default_factory=lambda: datetime.datetime.now(tz=datetime.timezone.utc)
+    )
+    content: str = ""
+    extra_frontmatter: dict = field(default_factory=dict)
+
+
+@dataclass
+class ArgumentInfo:
+    """Represents one parameter in a function/method signature."""
+    name: str
+    annotation: Optional[str] = None
+    default: Optional[str] = None
+    kind: str = "positional"
+
+
+@dataclass
+class AttributeInfo:
+    """Represents a class-level annotated attribute."""
+    name: str
+    annotation: Optional[str] = None
+    default: Optional[str] = None
+
+
+@dataclass
+class MethodInfo:
+    """Represents one method inside a class."""
+    name: str
+    signature: str
+    docstring: Optional[str] = None
+    decorators: list[str] = field(default_factory=list)
+    is_async: bool = False
+    args: list[ArgumentInfo] = field(default_factory=list)
+    returns: Optional[str] = None
+    line_number: int = 0
+
+    @property
+    def is_public(self) -> bool:
+        return not self.name.startswith("_")
+
+    @property
+    def is_dunder(self) -> bool:
+        return self.name.startswith("__") and self.name.endswith("__")
+
+
+@dataclass
+class FunctionInfo:
+    """Represents a top-level module function."""
+    name: str
+    module_name: str
+    source_file: str
+    signature: str
+    docstring: Optional[str] = None
+    decorators: list[str] = field(default_factory=list)
+    is_async: bool = False
+    args: list[ArgumentInfo] = field(default_factory=list)
+    returns: Optional[str] = None
+    is_exported: bool = False
+    line_number: int = 0
+
+    @property
+    def is_public(self) -> bool:
+        return not self.name.startswith("_")
+
+    @property
+    def concept_type(self) -> ConceptType:
+        return ConceptType.API if self.is_exported else ConceptType.FUNCTION
+
+
+@dataclass
+class ClassInfo:
+    """Represents a class definition extracted from AST."""
+    name: str
+    module_name: str
+    source_file: str
+    docstring: Optional[str] = None
+    bases: list[str] = field(default_factory=list)
+    attributes: list[AttributeInfo] = field(default_factory=list)
+    methods: list[MethodInfo] = field(default_factory=list)
+    decorators: list[str] = field(default_factory=list)
+    line_number: int = 0
+
+    @property
+    def public_methods(self) -> list[MethodInfo]:
+        return [m for m in self.methods if m.is_public]
+
+    @property
+    def dunder_methods(self) -> list[MethodInfo]:
+        return [m for m in self.methods if m.is_dunder]
+
+
+@dataclass
+class ModuleInfo:
+    """Represents a fully analyzed Python module file."""
+    name: str
+    source_file: str
+    docstring: Optional[str] = None
+    classes: list[ClassInfo] = field(default_factory=list)
+    functions: list[FunctionInfo] = field(default_factory=list)
+    exports: list[str] = field(default_factory=list)
+
+    @property
+    def public_functions(self) -> list[FunctionInfo]:
+        return [f for f in self.functions if f.is_public]