graphcore-distro 0.1.0__py3-none-any.whl

doc_topics.py

@@ -0,0 +1,75 @@
+"""Documentation topics contributed by the graphcore distro.
+
+These curated user guides live in the ``graphcore_user_guides`` content
+package. Their public paths are namespaced under ``distro`` by discovery.
+"""
+
+from graphcore.docs.docs_discovery import Doc
+
+TOPICS: dict[str, Doc] = {
+    "readme": Doc(
+        "graphcore_user_guides",
+        "getting_started.md",
+        "Setup, creating an app, and CLI live testing",
+    ),
+    "app-design": Doc(
+        "graphcore_user_guides",
+        "app_design/how_to_design_gc_apps.md",
+        "Design and build an app: the decisions, its TDD, building it, using it over MCP",
+    ),
+    "app-design/template": Doc(
+        "graphcore_user_guides",
+        "app_design/app_tdd_template.md",
+        "Fill-in technical design (TDD) for a new app",
+    ),
+    "app-design/example": Doc(
+        "graphcore_user_guides",
+        "app_design/stacks_tdd.md",
+        "Worked example: the Stacks app's technical design",
+    ),
+    "entities": Doc(
+        "graphcore_user_guides",
+        "entities.md",
+        "Entity types: typed fields and storage, queries, type metadata, references",
+    ),
+    "agent-views": Doc(
+        "graphcore_user_guides",
+        "agent_views.md",
+        "Agent views over MCP: rendering places, routes, tools and operations, the base views",
+    ),
+    "frontend": Doc(
+        "graphcore_user_guides",
+        "frontend.md",
+        "The web frontend: views, public pages, base path, layout, running strategies",
+    ),
+    "writing-strategies": Doc(
+        "graphcore_user_guides",
+        "writing_strategies.md",
+        "Writing strategies: apply, saving entities, retries, refusing requests, testing strategies and agent views",
+    ),
+    "custom-authorization": Doc(
+        "graphcore_user_guides",
+        "custom_authorization.md",
+        "Configure custom authorization for an app",
+    ),
+    "deployment-access": Doc(
+        "graphcore_user_guides",
+        "deployment_access.md",
+        "Administrators, groups, deployment roles, and what new users receive",
+    ),
+    "identity-infrastructure": Doc(
+        "graphcore_user_guides",
+        "identity_infrastructure.md",
+        "Identity domains, linking and token exchange; the local Keycloak, and any OIDC provider in production",
+    ),
+    "service-accounts": Doc(
+        "graphcore_user_guides",
+        "service_accounts.md",
+        "Service accounts: a process an app ships, signing in with its own client",
+    ),
+    "production": Doc(
+        "graphcore_user_guides",
+        "production.md",
+        "Running in production: what a project needs, settings, deploy steps",
+    ),
+}

graphcore_cli/__init__.py

@@ -0,0 +1,397 @@
+"""Console entry point for the ``graphcore`` command.
+
+Command modules (``*_cmd.py``) hold arg parsing and dispatch logic only; this
+module wires them onto one argparse tree. Scaffolding lives in
+``scaffold_cmd.py``; template assets live in ``graphcore_project_kit``.
+"""
+
+import argparse
+import sys
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path
+
+from .scaffold_cmd import startapp, startproject
+
+__all__ = ["main", "package_version", "startapp", "startproject"]
+
+
+def package_version() -> str:
+    try:
+        return version("graphcore-distro")
+    except PackageNotFoundError:
+        return "0+unknown"
+
+
+def cmd_run(args: argparse.Namespace) -> int:
+    import graphcore_project
+
+    port = args.port
+    if port is None:
+        root = graphcore_project.find_project_root() or Path.cwd()
+        port = graphcore_project.dotenv_port(root, "BACKEND_PORT", 8000)
+
+    return graphcore_project.run(debug=args.debug, host=args.host, port=port, role=args.role)
+
+
+def cmd_migrate(args: argparse.Namespace) -> int:
+    import graphcore_project
+
+    return graphcore_project.migrate_deployment()
+
+
+def cmd_db_create(args: argparse.Namespace) -> int:
+    import graphcore_project
+
+    return graphcore_project.create_database()
+
+
+def cmd_test(args: argparse.Namespace) -> int:
+    import subprocess
+
+    from graphcore_project import require_project_root
+
+    root = require_project_root(command="graphcore test")
+    return subprocess.run(
+        [sys.executable, "manage.py", "test", *args.passthrough],
+        cwd=root / "backend",
+    ).returncode
+
+
+def cmd_dev_reset(args: argparse.Namespace) -> int:
+    import subprocess
+
+    from graphcore_project import require_project_root
+
+    root = require_project_root(command="graphcore dev reset")
+    return subprocess.run([sys.executable, "manage.py", "dev_reset"], cwd=root / "backend").returncode
+
+
+def cmd_createadmin(args: argparse.Namespace) -> int:
+    import subprocess
+
+    from graphcore_project import require_project_root
+
+    from .docker_cmd import createadmin_manage_args
+
+    root = require_project_root(command="graphcore createadmin")
+    return subprocess.run(
+        [sys.executable, "manage.py", *createadmin_manage_args(args)], cwd=root / "backend",
+    ).returncode
+
+
+def cmd_policy(args: argparse.Namespace) -> int:
+    import subprocess
+
+    from graphcore_project import require_project_root
+
+    from .docker_cmd import policy_manage_args
+
+    root = require_project_root(command="graphcore policy")
+    return subprocess.run(
+        [sys.executable, "manage.py", *policy_manage_args(args)], cwd=root / "backend",
+    ).returncode
+
+
+def cmd_status(args: argparse.Namespace) -> int:
+    import subprocess
+
+    from graphcore_project import require_project_root
+
+    root = require_project_root(command="graphcore status")
+    return subprocess.run([sys.executable, "manage.py", "graphcore_status"], cwd=root / "backend").returncode
+
+
+def cmd_docker(args: argparse.Namespace) -> int:
+    from . import docker_cmd
+
+    handlers = {
+        "up": docker_cmd.docker_up,
+        "down": docker_cmd.docker_down,
+        "logs": docker_cmd.docker_logs,
+        "test": docker_cmd.docker_test,
+        "createadmin": docker_cmd.docker_createadmin,
+        "policy": docker_cmd.docker_policy,
+        "status": docker_cmd.docker_status,
+        "migrate": docker_cmd.docker_migrate,
+    }
+    return handlers[args.docker_command](args)
+
+
+def cmd_infra(args: argparse.Namespace) -> int:
+    from . import infra_cmd
+
+    handlers = {
+        "up": infra_cmd.infra_up,
+        "down": infra_cmd.infra_down,
+    }
+    return handlers[args.infra_command](args)
+
+
+def cmd_identity(args: argparse.Namespace) -> int:
+    from . import identity_cmd
+
+    handlers = {
+        "apply": identity_cmd.identity_apply,
+        "render": identity_cmd.identity_render,
+    }
+    return handlers[args.identity_command](args)
+
+
+def cmd_db(args: argparse.Namespace) -> int:
+    from . import db_cmd
+
+    handlers = {
+        "create": cmd_db_create,
+        "backup": db_cmd.db_backup,
+        "restore": db_cmd.db_restore,
+    }
+    return handlers[args.db_command](args)
+
+
+
+def _add_createadmin_arguments(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("user", help="Username or principal entity id (gc://...)")
+    parser.add_argument("--remove", action="store_true", help="Remove the user from the admins")
+    parser.add_argument("--force", action="store_true", help="Allow removing the last admin")
+
+
+LOCAL_FRAMEWORK_HELP = (
+    "Use this monorepo checkout's kernel, distro and built-in apps (editable installs, "
+    "live mounts, file: links) instead of the published packages"
+)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="graphcore")
+    parser.add_argument("--version", action="version", version=f"%(prog)s {package_version()}")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    project = subparsers.add_parser("startproject", help="Generate a graphcore deployment")
+    project.add_argument("name")
+    project.add_argument("directory", nargs="?")
+    project.add_argument("--local-framework", action="store_true", help=LOCAL_FRAMEWORK_HELP)
+    project.set_defaults(func=startproject)
+
+    app = subparsers.add_parser("startapp", help="Generate a graphcore app: under apps/ in a project, else in the current directory")
+    app.add_argument("name")
+    app.add_argument("--local-framework", action="store_true", help=LOCAL_FRAMEWORK_HELP + " (outside a project only)")
+    app.set_defaults(func=startapp)
+
+    run_parser = subparsers.add_parser(
+        "run",
+        help="Run the deployment on the host (uvicorn + Celery worker + Beat)",
+    )
+    run_parser.add_argument("--debug", action="store_true", help="Single-process debug mode")
+    run_parser.add_argument("--host", default="0.0.0.0")
+    run_parser.add_argument(
+        "--port",
+        type=int,
+        default=None,
+        help="Defaults to the deployment's .env BACKEND_PORT, then 8000.",
+    )
+    run_parser.add_argument(
+        "--role",
+        choices=["web", "worker", "beat", "all"],
+        default="all",
+        help="Which process(es) to run (default: all, bundled - ignored in --debug mode)",
+    )
+    run_parser.set_defaults(func=cmd_run)
+
+    migrate_parser = subparsers.add_parser(
+        "migrate",
+        help="Apply migrations under a Postgres advisory lock (safe to run from multiple replicas)",
+    )
+    migrate_parser.set_defaults(func=cmd_migrate)
+
+    test_parser = subparsers.add_parser(
+        "test",
+        help="Run python manage.py test on the host (passthrough args allowed)",
+    )
+    test_parser.add_argument(
+        "passthrough",
+        nargs="*",
+        default=[],
+        help="Args forwarded to manage.py test (e.g. graphcore.domain.entity.tests)",
+    )
+    test_parser.set_defaults(func=cmd_test)
+
+    dev = subparsers.add_parser("dev", help="Local dev conveniences")
+    dev_sub = dev.add_subparsers(dest="dev_command", required=True)
+
+    dev_reset = dev_sub.add_parser(
+        "reset",
+        help="Invalidate the entity cache (generation bump) without flushing sessions or other cache entries",
+    )
+    dev_reset.set_defaults(func=cmd_dev_reset)
+
+    createadmin = subparsers.add_parser(
+        "createadmin", help="Make a user a deployment administrator (or --remove one)",
+    )
+    _add_createadmin_arguments(createadmin)
+    createadmin.set_defaults(func=cmd_createadmin)
+
+    policy = subparsers.add_parser("policy", help="Print each entity type's effective access policy")
+    policy.add_argument("type_id", nargs="?", help="Only this entity_type_id (e.g. graphcore.Grant)")
+    policy.set_defaults(func=cmd_policy)
+
+    status = subparsers.add_parser(
+        "status", help="Show Celery workers, their kernel tasks, and what the scheduler holds",
+    )
+    status.set_defaults(func=cmd_status)
+
+    docker = subparsers.add_parser("docker", help="Manage the deployment's docker compose stack")
+    docker_sub = docker.add_subparsers(dest="docker_command", required=True)
+
+    up = docker_sub.add_parser("up", help="Start the backend container (uses shared `graphcore infra`)")
+    up.add_argument("--build", action="store_true", help="Build images before starting")
+    up.add_argument("-d", "--detach", action="store_true", help="Run in the background")
+    up.add_argument("--debug", action="store_true", help="Use the debug backend profile")
+    up.set_defaults(func=cmd_docker)
+
+    down = docker_sub.add_parser("down", help="Stop compose services")
+    down.add_argument("-v", "--volumes", action="store_true", help="Remove volumes too")
+    down.set_defaults(func=cmd_docker)
+
+    logs = docker_sub.add_parser("logs", help="Tail compose logs")
+    logs.add_argument("passthrough", nargs="*", default=["-f"])
+    logs.set_defaults(func=cmd_docker)
+
+    dtest = docker_sub.add_parser(
+        "test",
+        help="Run manage.py test inside the running backend container",
+    )
+    dtest.add_argument(
+        "passthrough",
+        nargs="*",
+        default=[],
+        help="Args forwarded to manage.py test",
+    )
+    dtest.set_defaults(func=cmd_docker)
+
+    dcreateadmin = docker_sub.add_parser(
+        "createadmin",
+        help="Make a user a deployment administrator inside the running backend container",
+    )
+    _add_createadmin_arguments(dcreateadmin)
+    dcreateadmin.set_defaults(func=cmd_docker)
+
+    dpolicy = docker_sub.add_parser(
+        "policy", help="Print each entity type's effective access policy (in the backend container)",
+    )
+    dpolicy.add_argument("type_id", nargs="?", help="Only this entity_type_id")
+    dpolicy.set_defaults(func=cmd_docker)
+
+    dstatus = docker_sub.add_parser(
+        "status",
+        help="Show Celery workers, their kernel tasks, and what the scheduler holds (in the backend container)",
+    )
+    dstatus.set_defaults(func=cmd_docker)
+
+    dmigrate = docker_sub.add_parser(
+        "migrate",
+        help="One-shot `graphcore migrate` via the `migrate` compose profile (multi-replica-safe)",
+    )
+    dmigrate.set_defaults(func=cmd_docker)
+
+    infra = subparsers.add_parser(
+        "infra",
+        help="Shared local Postgres + Redis used by all deployments on this machine",
+    )
+    infra_sub = infra.add_subparsers(dest="infra_command", required=True)
+
+    infra_up = infra_sub.add_parser("up", help="Start the shared containers (idempotent)")
+    infra_up.set_defaults(func=cmd_infra)
+
+    infra_down = infra_sub.add_parser("down", help="Stop the shared containers")
+    infra_down.add_argument(
+        "-v",
+        "--volumes",
+        action="store_true",
+        help="Also delete the shared data volume (ALL deployments' data)",
+    )
+    infra_down.set_defaults(func=cmd_infra)
+
+    identity = subparsers.add_parser(
+        "identity", help="The deployment's identity domain: the Keycloak realm its users sign in to")
+    identity_sub = identity.add_subparsers(dest="identity_command", required=True)
+
+    identity_apply = identity_sub.add_parser(
+        "apply",
+        help="Create or update this project's identity domain (Keycloak realm) from its declarations; idempotent",
+    )
+    identity_apply.set_defaults(func=cmd_identity)
+
+    identity_render = identity_sub.add_parser(
+        "render", help="Print the realm `apply` would create, secrets shown as their .env variables")
+    identity_render.add_argument(
+        "--with-secrets", action="store_true", help="Print the secret values instead of their variables")
+    identity_render.set_defaults(func=cmd_identity)
+
+    db = subparsers.add_parser("db", help="Postgres backup and restore for a deployment")
+    db_sub = db.add_subparsers(dest="db_command", required=True)
+
+    create = db_sub.add_parser(
+        "create",
+        help="Create the deployment's database if it doesn't exist yet (no-op otherwise)",
+    )
+    create.set_defaults(func=cmd_db)
+
+    backup = db_sub.add_parser(
+        "backup",
+        help="Chunked compressed pg_dump into <deployment>/backups/",
+    )
+    backup.add_argument(
+        "name",
+        nargs="?",
+        default=None,
+        help="Optional suffix appended to today's date folder name",
+    )
+    backup.set_defaults(func=cmd_db)
+
+    restore = db_sub.add_parser(
+        "restore",
+        help="Restore a backup folder created by graphcore db backup",
+    )
+    restore.add_argument("backup_path", help="Path to a backups/YYYY-MM-DD[-name] folder")
+    restore.add_argument("--host", default=None, help="Override POSTGRES_HOST")
+    restore.add_argument("--port", type=int, default=None, help="Override POSTGRES_PORT")
+    restore.add_argument("--user", default=None, help="Override POSTGRES_USER")
+    restore.add_argument("--database", default=None, help="Override POSTGRES_DB")
+    restore.add_argument(
+        "--force",
+        action="store_true",
+        help="Overwrite an existing database without prompting",
+    )
+    restore.set_defaults(func=cmd_db)
+
+    api = subparsers.add_parser("api", help="Live-test a running deployment over HTTP")
+    from . import api_cmd
+
+    api_cmd.add_arguments(api)
+
+    docs = subparsers.add_parser("docs", help="Read framework documentation for this install")
+    from . import docs_cmd
+
+    docs_cmd.add_arguments(docs)
+
+    frontend = subparsers.add_parser("frontend", help="Prepare and start the project frontend")
+    from . import frontend_cmd
+
+    frontend_cmd.add_arguments(frontend)
+
+    apps = subparsers.add_parser("apps", help="Inspect discovered graphcore apps")
+    from . import apps_cmd
+
+    apps_cmd.add_arguments(apps)
+
+    skills = subparsers.add_parser("skills", help="Manage framework-shipped Agent Skills in a deployment")
+    from . import skills_cmd
+
+    skills_cmd.add_arguments(skills)
+
+    args = parser.parse_args(argv)
+    return args.func(args) or 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())