gcontext-ai 0.2.1__py3-none-any.whl

core/__init__.py

@@ -0,0 +1 @@
+# empty package marker

core/kind_specs.py

@@ -0,0 +1,135 @@
+"""Per-kind module structure: required files, default growth folders, purpose.
+
+Single source of truth for how an `integration`, `task`, or `workflow`
+module is laid out on disk.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class KindSpec:
+    kind: str
+    purpose: str
+    required_files: list[str]
+    starter_file: str
+    starter_outline: str
+    default_growth_folders: list[dict]  # [{"name": "notes", "path": "notes/<date-slug>.md"}]
+
+
+KIND_SPECS: dict[str, KindSpec] = {
+    "integration": KindSpec(
+        kind="integration",
+        purpose="Reusable access to an external service, API, database, or local tool.",
+        required_files=["module.yaml", "llms.txt", "info.md"],
+        starter_file="info.md",
+        starter_outline="Purpose, Access, Operations, Example usage.",
+        default_growth_folders=[
+            {"name": "notes", "path": "notes/<date-slug>.md"},
+        ],
+    ),
+    "task": KindSpec(
+        kind="task",
+        purpose="A bounded outcome needing progress tracking, subtasks, findings.",
+        required_files=["module.yaml", "llms.txt", "brief.md", "status.md"],
+        starter_file="brief.md",
+        starter_outline="Goal and initial request; status.md tracks subtasks.",
+        default_growth_folders=[
+            {"name": "progress", "path": "progress/<date-slug>.md"},
+        ],
+    ),
+    "workflow": KindSpec(
+        kind="workflow",
+        purpose="A repeatable procedure or playbook that should improve across runs.",
+        required_files=["module.yaml", "llms.txt", "steps.md"],
+        starter_file="steps.md",
+        starter_outline="The repeatable steps, numbered.",
+        default_growth_folders=[
+            {"name": "runs", "path": "runs/<date-slug>.md"},
+            {"name": "lessons", "path": "lessons/<date-slug>.md"},
+        ],
+    ),
+}
+
+
+def render_kind_specs_md() -> str:
+    """Render KIND_SPECS as markdown for structure.md."""
+    lines: list[str] = []
+    for spec in KIND_SPECS.values():
+        lines.append(f"### `{spec.kind}`")
+        lines.append("")
+        lines.append(spec.purpose)
+        lines.append("")
+        lines.append("**Files written at creation:**")
+        for f in spec.required_files:
+            note = f" - {spec.starter_outline}" if f == spec.starter_file else ""
+            lines.append(f"- `{f}`{note}")
+        if spec.default_growth_folders:
+            lines.append("")
+            lines.append(
+                "**Default growth folders** (lazy: created on first entry; "
+                "seed these into `llms.txt` `## Where to write` at module creation):"
+            )
+            for ga in spec.default_growth_folders:
+                lines.append(f"- `{ga['name']}` -> `{ga['path']}`")
+        lines.append("")
+    return "\n".join(lines)
+
+
+@dataclass(frozen=True)
+class InfoSection:
+    name: str
+    purpose: str
+    format: str  # "freeform" or description of strict format
+
+
+# Core version: 6 sections (no "Python packages" -- that's added by gcontext Cloud)
+INTEGRATION_INFO_SECTIONS: list[InfoSection] = [
+    InfoSection(
+        "Purpose",
+        "One-line summary of what this integration gives the agent access to.",
+        "freeform",
+    ),
+    InfoSection(
+        "Where it lives",
+        "Upstream system: URL, host, endpoint, or local path.",
+        "freeform",
+    ),
+    InfoSection(
+        "Auth & access",
+        "How the agent authenticates. Required secret names are written as `UPPER_CASE` in backticks.",
+        "strict: secret names as `UPPER_CASE` backtick tokens",
+    ),
+    InfoSection(
+        "Key entities",
+        "Domain objects the agent can read or write.",
+        "freeform",
+    ),
+    InfoSection(
+        "Operations",
+        "Common calls or queries with short examples.",
+        "freeform",
+    ),
+    InfoSection(
+        "Examples",
+        "Runnable snippets.",
+        "freeform",
+    ),
+]
+
+
+def render_info_md_sections_md(sections: list[InfoSection] | None = None) -> str:
+    """Render the integration kind's expected info.md sections for structure.md.
+
+    Accepts an optional sections list so the platform can pass an extended
+    list (e.g., with "Python packages" section). Defaults to core's 6-section list.
+    """
+    sections = sections or INTEGRATION_INFO_SECTIONS
+    lines: list[str] = ["### `info.md` sections (integration kind)", ""]
+    for s in sections:
+        lines.append(f"- `## {s.name}` -- {s.purpose}")
+        if s.format != "freeform":
+            lines.append(f"  - Format: {s.format}")
+    lines.append("")
+    return "\n".join(lines)

core/llms_gen.py

@@ -0,0 +1,109 @@
+"""Generate workspace-level files: llms.txt, system.md, structure.md.
+
+These files are regenerated on every load/unload operation.
+"""
+import logging
+from pathlib import Path
+
+import yaml
+
+from core.kind_specs import render_kind_specs_md, render_info_md_sections_md
+from core.manifest import render_schema_md
+
+log = logging.getLogger(__name__)
+
+
+def extract_module_summary(llms_txt_content: str) -> str:
+    """Extract the > blockquote description from a module's llms.txt."""
+    for line in llms_txt_content.splitlines():
+        if line.startswith("> "):
+            return line[2:].strip()
+    return ""
+
+
+def generate_root_llms_txt(context_dir: Path) -> None:
+    """Generate root llms.txt from loaded modules' llms.txt files.
+
+    Skips dot-prefixed directories (e.g. .claude).
+    """
+    entries = []
+    for mod_dir in sorted(context_dir.iterdir()):
+        if not mod_dir.is_dir() or mod_dir.name.startswith("."):
+            continue
+        llms_file = mod_dir / "llms.txt"
+        if llms_file.exists():
+            summary = extract_module_summary(llms_file.read_text())
+        else:
+            summary = "Context module"
+        entries.append(f"- [{mod_dir.name}]({mod_dir.name}/llms.txt): {summary}")
+
+    lines = ["# Context", ""]
+    lines.extend(entries)
+    (context_dir / "llms.txt").write_text("\n".join(lines) + "\n")
+
+
+def generate_structure_md(context_dir: Path, info_sections: list | None = None) -> None:
+    """Write context/structure.md from manifest schema and kind specs.
+
+    Auto-generated reference for module.yaml fields, per-kind file
+    requirements, and info.md section structure.
+
+    Accepts optional info_sections so the platform can pass its extended
+    list (with "Python packages" section). Defaults to core's 6-section list.
+    """
+    body = "\n".join([
+        "# Module Structure",
+        "",
+        "Auto-generated from `manifest.py` and `kind_specs.py`. Do not edit by hand.",
+        "",
+        render_schema_md(),
+        "",
+        "## Module kinds",
+        "",
+        render_kind_specs_md(),
+        "## Starter file structure",
+        "",
+        render_info_md_sections_md(info_sections),
+    ])
+    (context_dir / "structure.md").write_text(body)
+
+
+def generate_system_md(context_dir: Path, template_content: str) -> None:
+    """Write context/system.md from a template string + loaded modules table.
+
+    The caller is responsible for reading/assembling the template content.
+    This function appends the loaded modules table at the end.
+    Skips dot-prefixed directories.
+    """
+    rows: list[tuple[str, str, str]] = []
+    for mod_dir in sorted(context_dir.iterdir()):
+        if not mod_dir.is_dir() or mod_dir.name.startswith("."):
+            continue
+        kind = "unknown"
+        manifest_file = mod_dir / "module.yaml"
+        if manifest_file.exists():
+            try:
+                data = yaml.safe_load(manifest_file.read_text())
+                kind = data.get("kind", "integration") if data else "unknown"
+            except Exception:
+                log.warning("Failed to parse %s", manifest_file)
+        llms_file = mod_dir / "llms.txt"
+        summary = ""
+        if llms_file.exists():
+            summary = extract_module_summary(llms_file.read_text())
+        rows.append((mod_dir.name, kind, summary))
+
+    lines = [
+        "",
+        "## Loaded modules",
+        "",
+    ]
+    if rows:
+        lines.append("| Module | Kind | Summary |")
+        lines.append("|--------|------|---------|")
+        for name, kind, summary in rows:
+            lines.append(f"| {name} | {kind} | {summary} |")
+    else:
+        lines.append("No modules loaded.")
+
+    (context_dir / "system.md").write_text(template_content + "\n".join(lines) + "\n")

core/manifest.py

@@ -0,0 +1,225 @@
+"""Module manifest (module.yaml) read/write service.
+
+Each module declares its name, kind, secrets, dependencies, and optional
+jobs in module.yaml. Replaces per-module .env.schema and requirements.txt.
+"""
+import re
+import typing
+from pathlib import Path
+from typing import Literal
+
+import yaml
+from pydantic import BaseModel, Field, field_validator
+
+ModuleKind = Literal["integration", "task", "workflow"]
+
+
+_EVERY_RE = re.compile(r"^(\d+)([smh])$")
+_EVERY_UNIT_SECONDS = {"s": 1, "m": 60, "h": 3600}
+
+# Must match jobs.TICK_SECONDS — keep as a constant here to avoid
+# importing jobs.py from manifest.py (circular).
+_MIN_EVERY_SECONDS = 30
+
+
+def parse_every(value: str) -> int:
+    """Convert '30s' / '5m' / '1h' to a number of seconds.
+
+    Raises ValueError on any malformed input or values below the
+    scheduler tick (30 s) — sub-tick intervals would round up anyway
+    and surprise the user.
+    """
+    if not isinstance(value, str):
+        raise ValueError(f"every must be a string, got {type(value).__name__}")
+    match = _EVERY_RE.fullmatch(value)
+    if not match:
+        raise ValueError(
+            f"invalid every '{value}': expected <digits><s|m|h>, e.g. '30s', '5m', '1h'"
+        )
+    n = int(match.group(1))
+    if n == 0:
+        raise ValueError(f"invalid every '{value}': must be > 0")
+    seconds = n * _EVERY_UNIT_SECONDS[match.group(2)]
+    if seconds < _MIN_EVERY_SECONDS:
+        raise ValueError(
+            f"invalid every '{value}': minimum is {_MIN_EVERY_SECONDS}s"
+        )
+    return seconds
+
+
+class JobSpec(BaseModel):
+    name: str = Field(..., description="Job identifier; unique within the module.")
+    script: str = Field(
+        ...,
+        description="Relative path to the script inside the module directory. Absolute paths and `..` traversal are rejected.",
+    )
+    every: str = Field(
+        ...,
+        description="Cron-like cadence as `<digits><s|m|h>` (e.g. `30s`, `5m`, `1h`). Minimum 30s.",
+    )
+
+    @field_validator("script")
+    @classmethod
+    def _no_absolute_or_traversal(cls, v: str) -> str:
+        if v.startswith("/") or ".." in Path(v).parts:
+            raise ValueError(f"invalid script path '{v}': must be relative inside the module")
+        return v
+
+    @field_validator("every")
+    @classmethod
+    def _validate_every(cls, v: str) -> str:
+        parse_every(v)  # raises on bad values
+        return v
+
+    @property
+    def every_seconds(self) -> int:
+        return parse_every(self.every)
+
+
+class ModuleManifest(BaseModel):
+    name: str = Field(
+        ...,
+        description="Folder slug; must match the module directory name.",
+    )
+    kind: ModuleKind = Field(
+        default="integration",
+        description='One of: "integration", "task", "workflow". Drives how the module is rendered in the sidebar.',
+    )
+    archived: bool = Field(
+        default=False,
+        description="Hide from the active sidebar without deleting. Archived modules appear under a collapsed Archived section and cannot be loaded into the workspace.",
+    )
+    secrets: list[str] = Field(
+        default_factory=list,
+        description="Environment variable names this module needs at runtime. Resolved via varlock from the workspace .env.schema.",
+    )
+    dependencies: list[str] = Field(
+        default_factory=list,
+        description="Python packages required at runtime. Installed into the platform venv at boot.",
+    )
+    icon: str = Field(
+        default="",
+        description="Icon name for the module's app card (e.g. 'globe', 'server'). Empty means auto-derived.",
+    )
+    jobs: list[JobSpec] = Field(
+        default_factory=list,
+        description="Cron-like scheduled scripts owned by this module.",
+    )
+
+
+def read_manifest(module_dir: Path) -> ModuleManifest:
+    """Read module.yaml from a module directory.
+
+    Returns a manifest with defaults (name inferred from dir) if the
+    file doesn't exist.
+    """
+    manifest_path = module_dir / "module.yaml"
+    if not manifest_path.exists():
+        return ModuleManifest(name=module_dir.name)
+    raw = yaml.safe_load(manifest_path.read_text()) or {}
+    raw.setdefault("name", module_dir.name)
+    return ModuleManifest(**raw)
+
+
+def write_manifest(module_dir: Path, manifest: ModuleManifest) -> None:
+    """Write a ModuleManifest to module.yaml, omitting empty optional fields."""
+    data: dict[str, str | bool | list[str]] = {"name": manifest.name}
+    if manifest.kind != "integration":
+        data["kind"] = manifest.kind
+    if manifest.archived:
+        data["archived"] = manifest.archived
+    if manifest.icon:
+        data["icon"] = manifest.icon
+    if manifest.secrets:
+        data["secrets"] = manifest.secrets
+    if manifest.dependencies:
+        data["dependencies"] = manifest.dependencies
+    if manifest.jobs:
+        data["jobs"] = [
+            {"name": j.name, "script": j.script, "every": j.every}
+            for j in manifest.jobs
+        ]
+    (module_dir / "module.yaml").write_text(
+        yaml.dump(data, default_flow_style=False, sort_keys=False)
+    )
+
+
+_SLUG_NON_ALPHANUM = re.compile(r"[^a-z0-9-]")
+_SLUG_DASH_RUN = re.compile(r"-+")
+
+
+def slugify_task_name(name: str) -> str:
+    """Convert a human task name to a folder-safe slug."""
+    slug = name.strip().lower().replace("_", "-")
+    slug = _SLUG_NON_ALPHANUM.sub("-", slug)
+    slug = _SLUG_DASH_RUN.sub("-", slug)
+    return slug.strip("-")
+
+
+_PRIMITIVE_NAMES = {
+    str: "str",
+    int: "int",
+    float: "float",
+    bool: "bool",
+}
+
+
+def _format_default(field) -> str:
+    if field.is_required():
+        return "required"
+    factory = field.default_factory
+    if factory is not None:
+        try:
+            default = factory()
+        except TypeError:
+            default = None
+    else:
+        default = field.default
+    if isinstance(default, bool):
+        return "default false" if default is False else "default true"
+    if isinstance(default, str):
+        return f'default "{default}"'
+    if isinstance(default, list) and not default:
+        return "default []"
+    return f"default {default!r}"
+
+
+def _format_type(annotation) -> str:
+    if annotation in _PRIMITIVE_NAMES:
+        return _PRIMITIVE_NAMES[annotation]
+    origin = getattr(annotation, "__origin__", None)
+    if origin is list:
+        (inner,) = annotation.__args__
+        if inner is JobSpec:
+            return "list[JobSpec]"
+        return f"list[{_PRIMITIVE_NAMES.get(inner, inner.__name__)}]"
+    if typing.get_origin(annotation) is Literal:
+        return " | ".join(repr(v) for v in typing.get_args(annotation))
+    return getattr(annotation, "__name__", str(annotation))
+
+
+def render_schema_md() -> str:
+    """Render ModuleManifest as a markdown schema block for prompt injection.
+
+    Walks the model's fields and emits one bullet per field with type,
+    default, and description. Single source of truth for what the AI
+    should write into module.yaml — adding a new field here makes it
+    visible to the chat agent automatically.
+    """
+    lines = ["## module.yaml schema", ""]
+    for field_name, field in ModuleManifest.model_fields.items():
+        type_str = _format_type(field.annotation)
+        default_str = _format_default(field)
+        desc = field.description or ""
+        lines.append(f"- `{field_name}` ({type_str}, {default_str}) — {desc}")
+        if type_str == "list[JobSpec]":
+            for sub_name, sub in JobSpec.model_fields.items():
+                sub_type = _format_type(sub.annotation)
+                sub_default = _format_default(sub)
+                sub_desc = sub.description or ""
+                lines.append(f"  - `{sub_name}` ({sub_type}, {sub_default}) — {sub_desc}")
+    lines.append("")
+    lines.append(
+        "Omit fields that match their default. Unknown fields are rejected."
+    )
+    return "\n".join(lines)

core/schemas.py

@@ -0,0 +1,22 @@
+import re
+
+_VALID_MODULE_NAME = re.compile(r"^[a-zA-Z0-9][a-zA-Z0-9_-]*$")
+
+
+def validate_module_name(name: str) -> str:
+    name = name.strip()
+    if not name or not _VALID_MODULE_NAME.match(name):
+        raise ValueError(
+            f"Invalid module name: '{name}'. "
+            "Must start with a letter or number, then letters, numbers, hyphens, underscores."
+        )
+    return name
+
+
+def validate_module_file_path(file_path: str) -> str:
+    file_path = file_path.strip().strip("/")
+    if not file_path:
+        raise ValueError("File path cannot be empty")
+    if ".." in file_path:
+        raise ValueError("File path cannot contain '..'")
+    return file_path

core/templates/module_features.md

@@ -0,0 +1,9 @@
+# Module Features — Optional Capabilities
+
+A module is just a folder. Beyond `module.yaml` + `llms.txt` + the kind's starter file (info.md / brief.md / steps.md), a module can optionally carry:
+
+## Scripts
+
+Plain Python files inside the module that the agent can run on demand. The canonical example is `verify.py` — a quick sanity check that the integration's credentials and network access work.
+
+When to add one: when the module benefits from a repeatable check, fetch, or transformation that the user (or another turn) will want to invoke later.

core/templates/principles.md

@@ -0,0 +1,29 @@
+# Principles — Modifying Context
+
+These are the rules for creating, editing, or extending modules.
+
+## Module locations
+
+Modules live at `modules-repo/<slug>/`. The `context/` directory contains symlinks for the subset of modules currently loaded into the active workspace — **it is a view, not a storage location.**
+
+Two operations that look similar but are NOT the same:
+
+- **Create / edit a module.** You write files at `modules-repo/<slug>/...`. This is the only kind of write you perform.
+- **Load a module into the workspace.** This creates a symlink inside `context/`. It is managed by the `gcontext` CLI, not by you.
+
+Each module is a folder with at least `module.yaml` and `llms.txt`.
+
+## Reading context before modifying
+
+Before answering anything that references or implies a topic likely covered by an existing module, read that module's `llms.txt` first. If `llms.txt` declares a `## Where to write` section, that section governs where any subsequent appends go (path, naming pattern, template). Do NOT invent a new location.
+
+If no module matches, you may answer from general knowledge — but if the conversation produces durable content (a finding, a note worth keeping, a new procedure), propose a new module rather than silently dropping it.
+
+## Module schema and kinds
+
+See [structure.md](structure.md) for the authoritative module.yaml schema and the per-kind file layout (integration / task / workflow). That file is auto-generated from code — read it; do not invent fields.
+
+## When to propose a new module vs append to an existing one
+
+- **Append** when the content is one more instance of a pattern the module already tracks (another note, another run, another finding).
+- **New module** when the content concerns a different external service, a different task with its own goal, or a different repeatable procedure. New modules cost almost nothing — favor a small new module over stretching an existing one.

core/templates/system.md

@@ -0,0 +1,54 @@
+# System
+
+You are an AI agent powered by loaded context modules.
+
+You are direct, efficient, and familiar with the loaded context. No hedging, no filler. Lead with the answer.
+
+## Two responsibilities
+
+1. **Operate modules** — read context, run scripts, answer questions. This file covers that.
+2. **Modify context** — create or edit modules. See [principles.md](principles.md) before doing this.
+
+## How to operate a module
+
+**CRITICAL: Assume every question is potentially answerable through your modules. Always navigate the `llms.txt` tree before claiming you can't help. Never dismiss a question as out of scope without checking first.**
+
+When asked anything, start by asking: **"Which module do I need?"**
+
+1. Read `llms.txt` — see all loaded modules with one-line descriptions
+2. Pick the relevant module(s) based on the question
+3. Read that module's `llms.txt` to find the specific file you need
+4. Read the actual content, write a script if needed, and get the answer
+
+## Searching inside modules
+
+Your working directory uses symlinks to loaded modules. **Glob and Grep do not follow symlinks**, so they cannot find files inside modules from the workspace root.
+
+To search or list files within a module, point the tool at the module's real path:
+- **Glob/Grep path**: `modules-repo/<module-name>/` (not the workspace root)
+- **Read**: works normally with relative paths like `<module-name>/file.md`
+
+When module content references a file in another module (e.g. `ai-browsing/stripe/file.md`), resolve it with Read from the workspace root first. If the module isn't loaded, read from `modules-repo/<module-name>/` instead.
+
+## Setup per turn
+
+1. Read [llms.txt](llms.txt) — orient yourself in the module hierarchy
+2. For any module you need, read its `module.yaml` — declares required secrets and dependencies
+
+## Secrets
+
+See [secrets.md](secrets.md) for how secrets work in this environment.
+
+A module needs secrets if and only if its `module.yaml` declares a `secrets:` list (variable names only, no values).
+
+## Vocabulary
+
+"Task", "integration", and "workflow" are **module kinds** — not abstract concepts. When the user says "create a task", "add an integration", or "set up a workflow", they mean create a new module with that kind. See [structure.md](structure.md) for the file layout of each kind.
+
+## Module features — scripts, cron jobs, apps
+
+Modules can carry scripts, scheduled cron jobs, and browser apps. If the user asks to set up a cron job, build an app, add a verify script, or any similar capability, read [module_features.md](module_features.md) for the catalog and conventions.
+
+## Modifying context
+
+If you are asked to create a task, add an integration, start a workflow, create a new module, edit module files, or change anything in `modules-repo/<slug>/`, read [principles.md](principles.md) and [structure.md](structure.md) first. They own the rules for where things go, module kinds, and how writes are gated.

gcontext/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.2.1"