dataface 0.1.6.dev34__py3-none-any.whl → 0.1.6.dev76__py3-none-any.whl

dataface/__init__.py

@@ -22,9 +22,8 @@ Quick Start:
     ...     face = result.face
     ...
     ...     # Create executor and render
-    ...     from dataface.core.compile.config import load_project_sources
     ...     from dataface.core.project import Project
-    ...     registry = build_adapter_registry(Path.cwd(), project_sources=load_project_sources(Project(Path.cwd())))
+    ...     registry = build_adapter_registry(Project(Path.cwd()))
     ...     executor = Executor(face, registry, query_registry=result.query_registry)
     ...     svg = render(face, executor, format="svg")
 """

dataface/agent_api/_paths.py

@@ -11,7 +11,7 @@ from dataface.core.project_roots import (
     find_dft_root as find_dft_root,
 )
 from dataface.core.scoped_paths import (
-    resolve_scoped_path as _core_resolve_scoped_path,
+    resolve_scoped_path as resolve_scoped_path,
 )
 
 
@@ -45,26 +45,12 @@ def resolve_project_dir_from_paths(
     return resolve_project_dir(None)
 
 
-def resolve_scoped_path(path: Path, project_dir: Path | None = None) -> Path:
-    """agent_api wrapper: resolves `None → cwd-walked root` at the boundary,
-    then delegates to `core.scoped_paths.resolve_scoped_path`.
-
-    Absolute paths with no explicit `project_dir` resolve directly (no
-    containment check) — the caller supplied the path, so no project context is
-    needed to validate containment.
-    """
-    if path.is_absolute() and project_dir is None:
-        return path.resolve()
-    return _core_resolve_scoped_path(path, resolve_project_dir(project_dir))
-
-
-def no_project_hint(project_dir: Path | None) -> str:
+def no_project_hint(project_root: Path) -> str:
     """Return a hint string when no project marker is found, else empty string."""
-    check = project_dir if project_dir is not None else Path.cwd()
-    if find_dft_root(check) is not None:
+    if find_dft_root(project_root) is not None:
         return ""
     return (
-        f" No Dataface project marker found at or above {check}."
+        f" No Dataface project marker found at or above {project_root}."
         f" Run from inside a Dataface project, or set project_dir."
     )
 
@@ -79,7 +65,7 @@ class FaceRenderContext:
     """
 
     face_file: Path
-    scoped_path: Path | None
+    scoped_path: Path
     scoped_base: Path
     project_root: Path
     output_dir: Path
@@ -88,37 +74,34 @@ class FaceRenderContext:
 
 def build_face_render_context(
     face_path: Path,
-    project_dir: Path | None = None,
+    project_dir: Path,
 ) -> FaceRenderContext:
     """Resolve a face path and walk for dbt context.
 
-    ``project_dir=None`` means "walk freely from the face's parent" — used by
-    the CLI when ``--project-dir`` is omitted so a face under a dbt sub-project
-    still anchors on that sub-project's root. A given ``project_dir`` is
-    authoritative; the walk only contributes the dbt project path.
+    ``project_dir`` is authoritative; the walk only contributes the dbt project
+    path. Callers must resolve their project dir first (e.g. via
+    ``resolve_project_dir(raw_dir)`` at the CLI boundary).
     """
     if face_path.is_absolute():
         face_file = face_path.resolve()
     elif ".." in face_path.parts:
         face_file = (Path.cwd() / face_path).resolve()
     else:
-        anchor = (
-            project_dir.resolve()
-            if project_dir is not None
-            else resolve_project_dir(None)
-        )
-        face_file = (anchor / face_path).resolve()
-
-    walk_root, dbt_project_path = discover_render_context(
+        face_file = (project_dir / face_path).resolve()
+
+    _, dbt_project_path = discover_render_context(
         face_file.parent,
         discovery_boundary_for_face(face_file.parent, project_dir),
     )
-    project_root = project_dir.resolve() if project_dir is not None else walk_root
+    project_root = project_dir
 
     try:
-        scoped_path: Path | None = face_file.relative_to(project_root)
+        scoped_path: Path = face_file.relative_to(project_root)
     except ValueError:
-        scoped_path = face_file
+        raise ValueError(
+            f"Face file {face_file} is outside project_dir {project_root}. "
+            f"Pass an explicit --project-dir that contains the face file."
+        ) from None
 
     return FaceRenderContext(
         face_file=face_file,
@@ -143,18 +126,15 @@ class YamlRenderContext:
 
 
 def build_yaml_render_context(
-    project_dir: Path | None = None,
+    project_dir: Path,
 ) -> YamlRenderContext:
     """Walk for dbt context anchored at the given project root.
 
-    ``project_dir=None`` walks from cwd to discover the project root; a given
-    ``project_dir`` is authoritative.
+    ``project_dir`` is authoritative. Callers must resolve their project dir
+    first (e.g. via ``resolve_project_dir(raw_dir)`` at the CLI boundary).
     """
-    anchor = (
-        project_dir.resolve() if project_dir is not None else resolve_project_dir(None)
-    )
-    walk_root, dbt_project_path = discover_render_context(anchor, None)
-    project_root = anchor if project_dir is not None else walk_root
+    project_root = project_dir.resolve()
+    _, dbt_project_path = discover_render_context(project_root, None)
     return YamlRenderContext(
         project_root=project_root,
         output_dir=project_root,

dataface/agent_api/chat.py

@@ -24,6 +24,7 @@ from dataface.ai.agent import run_agent
 from dataface.ai.context import DatafaceAIContext
 from dataface.ai.events import AgentEvent
 from dataface.ai.llm import create_client
+from dataface.core.project import Project
 
 if TYPE_CHECKING:
     from dataface.ai.external_mcp import ExternalMCPManager
@@ -71,26 +72,27 @@ class ChatSessionSummary:
 def start_session(
     *,
     model: str | None = None,
-    project_dir: Path | None = None,
+    project: Project,
     server_port: int | None = None,
 ) -> ChatSession:
     """Create a new chat session.
 
     Args:
         model: LLM model name, optionally provider-prefixed.
-        project_dir: Working directory for the session. Defaults to cwd.
+        project: The Dataface project for this session.
         server_port: Port of the embedded HTTP preview server, if running.
     """
     from dataface.agent_api.project_session import ProjectSession
     from dataface.core.execute.adapters import LOCAL_AUTHORING_REGISTRY_KWARGS
 
-    cwd = (project_dir or Path.cwd()).resolve()
     client = create_client(model=model)
     context = DatafaceAIContext(
-        project_session=ProjectSession.open(cwd, **LOCAL_AUTHORING_REGISTRY_KWARGS),
+        project_session=ProjectSession.from_project(
+            project, **LOCAL_AUTHORING_REGISTRY_KWARGS
+        ),
         server_port=server_port,
     )
-    writer, _ = new_session(cwd, provider=client.provider, model=client.model)
+    writer, _ = new_session(project.root, provider=client.provider, model=client.model)
     return ChatSession(
         session_id=writer.session_id,
         messages=[],
@@ -106,7 +108,7 @@ def start_session(
 def resume_session(
     session_id: str,
     *,
-    project_dir: Path | None = None,
+    project: Project,
     server_port: int | None = None,
     model: str | None = None,
     max_tokens: int = 32_000,
@@ -115,7 +117,7 @@ def resume_session(
 
     Args:
         session_id: The session id to resume.
-        project_dir: Working directory for the resumed session. Defaults to cwd.
+        project: The Dataface project for the resumed session.
         server_port: Port of the embedded HTTP preview server, if running.
         model: LLM model to use. Defaults to the same provider as the session.
         max_tokens: Token budget for trimming old messages. 0 disables trimming.
@@ -126,7 +128,6 @@ def resume_session(
     from dataface.agent_api.project_session import ProjectSession
     from dataface.core.execute.adapters import LOCAL_AUTHORING_REGISTRY_KWARGS
 
-    cwd = (project_dir or Path.cwd()).resolve()
     client = create_client(model=model)
 
     messages, meta, _ = load_session_for_resume(
@@ -143,10 +144,12 @@ def resume_session(
         )
 
     context = DatafaceAIContext(
-        project_session=ProjectSession.open(cwd, **LOCAL_AUTHORING_REGISTRY_KWARGS),
+        project_session=ProjectSession.from_project(
+            project, **LOCAL_AUTHORING_REGISTRY_KWARGS
+        ),
         server_port=server_port,
     )
-    writer, _ = new_session(cwd, provider=client.provider, model=client.model)
+    writer, _ = new_session(project.root, provider=client.provider, model=client.model)
     return ChatSession(
         session_id=session_id,
         messages=messages,

dataface/agent_api/dashboards.py

@@ -18,6 +18,7 @@ from dataface.core.compile import Face, compile_file
 from dataface.core.compile.errors import DatafaceError
 from dataface.core.dashboard import RenderedDashboard as RenderedDashboard
 from dataface.core.errors import DF_UNKNOWN_INTERNAL, StructuredError
+from dataface.core.project import Project
 from dataface.core.render.warnings.base import RenderWarning
 
 # ---------------------------------------------------------------------------
@@ -193,12 +194,12 @@ def list_dashboards(
 def get_dashboard(
     path: Path,
     *,
-    project_dir: Path,
+    project: Project,
     include_raw: bool = False,
 ) -> CompiledDashboard:
     """Get the compiled structure of a dashboard."""
     try:
-        file_path = resolve_scoped_path(path, project_dir)
+        file_path = resolve_scoped_path(path, project.root)
     except ValueError as exc:
         return CompiledDashboard(
             success=False,
@@ -243,7 +244,7 @@ def get_dashboard(
             ],
         )
 
-    result = compile_file(file_path)
+    result = compile_file(file_path, project=project)
     return CompiledDashboard(
         success=result.success,
         dashboard=result.face if result.success else None,

dataface/agent_api/describe.py

@@ -21,6 +21,7 @@ from dataface.core.compile.models.query.normalized import (
     ValuesQuery,
 )
 from dataface.core.errors import DF_UNKNOWN_INTERNAL, StructuredError
+from dataface.core.project import Project
 
 # Chart-encoding fields surfaced to agents. Covers the stable channel fields
 # across chart families. `label` is excluded — it's a KPI-specific render hint,
@@ -190,14 +191,14 @@ def _encoding_for_chart(chart: Chart) -> dict[str, Any]:
 # ---------------------------------------------------------------------------
 
 
-def describe_face(path: Path, *, project_dir: Path) -> DescribeFaceResult:
+def describe_face(path: Path, *, project: Project) -> DescribeFaceResult:
     """Describe the structure of a face: queries, charts, variables, layout."""
     from dataface.agent_api._paths import no_project_hint, resolve_scoped_path
     from dataface.core.compile.compiler import compile_file
     from dataface.core.compile.errors import DatafaceError
 
     try:
-        resolved = resolve_scoped_path(path, project_dir)
+        resolved = resolve_scoped_path(path, project.root)
     except ValueError as exc:
         return DescribeFaceResult(
             success=False,
@@ -210,7 +211,7 @@ def describe_face(path: Path, *, project_dir: Path) -> DescribeFaceResult:
         )
 
     if not resolved.exists():
-        hint = no_project_hint(project_dir)
+        hint = no_project_hint(project.root)
         return DescribeFaceResult(
             success=False,
             path=path,
@@ -223,7 +224,7 @@ def describe_face(path: Path, *, project_dir: Path) -> DescribeFaceResult:
         )
 
     try:
-        result = compile_file(resolved)
+        result = compile_file(resolved, project=project)
     except OSError as exc:
         return DescribeFaceResult(
             success=False,
@@ -305,7 +306,7 @@ def describe_face(path: Path, *, project_dir: Path) -> DescribeFaceResult:
 def describe_paths(
     paths: list[Path],
     *,
-    project_dir: Path,
+    project: Project,
 ) -> list[DescribeFaceResult]:
     """Describe N face files / directories.
 
@@ -315,13 +316,13 @@ def describe_paths(
     """
     out: list[DescribeFaceResult] = []
     for p in paths:
-        out.extend(_describe_one_path(p, project_dir))
+        out.extend(_describe_one_path(p, project))
     return out
 
 
 def _describe_one_path(
     path: Path,
-    project_dir: Path,
+    project: Project,
 ) -> list[DescribeFaceResult]:
     """Per-argv expansion: file → [one], dir → walk."""
     # WHY: dataface.core.inspect.manifest_utils triggers the inspect package
@@ -332,7 +333,7 @@ def _describe_one_path(
     from dataface.core.inspect.manifest_utils import INSPECT_TEMPLATE_MANIFEST
 
     try:
-        resolved = resolve_scoped_path(path, project_dir)
+        resolved = resolve_scoped_path(path, project.root)
     except ValueError as exc:
         return [
             DescribeFaceResult(
@@ -347,7 +348,7 @@ def _describe_one_path(
         ]
 
     if not resolved.is_dir():
-        return [describe_face(resolved, project_dir=project_dir)]
+        return [describe_face(resolved, project=project)]
 
     template_dirs = {m.parent for m in resolved.glob(f"**/{INSPECT_TEMPLATE_MANIFEST}")}
     yaml_files = sorted(
@@ -368,4 +369,4 @@ def _describe_one_path(
                 ],
             )
         ]
-    return [describe_face(f, project_dir=project_dir) for f in yaml_files]
+    return [describe_face(f, project=project) for f in yaml_files]

dataface/agent_api/pack.py

@@ -18,7 +18,6 @@ from pathlib import Path
 import yaml
 from pydantic import BaseModel
 
-from dataface.core.compile.config import load_project_sources
 from dataface.core.execute.adapters import AdapterRegistry, build_adapter_registry
 from dataface.core.inspect.resolver import LayeredSchemaResolver
 from dataface.core.pack.models import PackProposal, ProposedDashboard
@@ -140,16 +139,16 @@ def _collect_source_entries(
 
 
 def propose_pack(
-    project_dir: Path,
+    project: Project,
     mode: str | None = None,
 ) -> tuple[PackProposal, Path]:
     """Read schema via the resolver and emit a deterministic PackProposal.
 
     The proposal is written to
-    ``<project_dir>/target/dataface/proposals/<slug>/proposal.yml``.
+    ``<project.root>/target/dataface/proposals/<slug>/proposal.yml``.
 
     Args:
-        project_dir: Root of the Dataface project (contains ``dataface.yml``).
+        project: Dataface project (root must contain ``dataface.yml``).
         mode: Organization mode override (``"connector-first"``,
             ``"domain-first"``, or ``"hybrid"``). When ``None``, the planner
             chooses automatically.
@@ -160,17 +159,15 @@ def propose_pack(
         of the written YAML file.
 
     Raises:
-        FileNotFoundError: When *project_dir* does not exist.
+        FileNotFoundError: When ``project.root`` does not exist.
         ValueError: When no SQL sources are configured in the project, or when
             all configured sources are unreachable.
     """
-    project_dir = project_dir.resolve()
+    project_dir = project.root
     if not project_dir.exists():
         raise FileNotFoundError(f"Project directory not found: {project_dir}")
 
-    registry = build_adapter_registry(
-        project_dir, project_sources=load_project_sources(Project(project_dir))
-    )
+    registry = build_adapter_registry(project)
     sql_sources = registry.list_sql_sources()
 
     if not sql_sources:
@@ -409,7 +406,7 @@ def _validate_scaffold_targets(
 
 def apply_proposal(
     proposal: PackProposal,
-    project_dir: Path,
+    project: Project,
     overwrite: bool = False,
 ) -> ScaffoldResult:
     """Apply an approved PackProposal, writing a sparse ``faces/`` folder tree.
@@ -426,7 +423,7 @@ def apply_proposal(
 
     Args:
         proposal: An approved :class:`~dataface.core.pack.models.PackProposal`.
-        project_dir: Dataface project root (the directory containing
+        project: Dataface project (root is the directory containing
             ``dataface.yml``).
         overwrite: When ``False`` (default), existing non-empty files are
             skipped and recorded in ``ScaffoldResult.skipped_files``. When
@@ -434,24 +431,23 @@ def apply_proposal(
 
     Returns:
         A :class:`ScaffoldResult` with ``created_files``, ``skipped_files``,
-        and ``errors`` (relative to ``project_dir``).
+        and ``errors`` (relative to ``project.root``).
 
     Raises:
         ValueError: When any generated file fails ``validate_paths()``.
     """
     from dataface.agent_api.validate import validate_paths
 
-    project_dir = project_dir.resolve()
     result = ScaffoldResult()
     validated_paths: list[Path] = []
     partial_targets, landing_targets, dashboard_targets = _validate_scaffold_targets(
         proposal,
-        project_dir,
+        project.root,
     )
 
     # Ensure base dirs exist
-    (project_dir / "faces").mkdir(exist_ok=True)
-    (project_dir / "faces" / "partials").mkdir(exist_ok=True)
+    (project.root / "faces").mkdir(exist_ok=True)
+    (project.root / "faces" / "partials").mkdir(exist_ok=True)
 
     # Write partials — skipped by validate_paths (_*.yml convention)
     for partial_filename, partial_path, rel in partial_targets:
@@ -490,7 +486,7 @@ def apply_proposal(
 
     # Validate gate — validate all newly written face files
     if validated_paths:
-        validate_results = validate_paths(validated_paths, project_dir=project_dir)
+        validate_results = validate_paths(validated_paths, project=project)
         for vr in validate_results:
             if not vr.success:
                 for err in vr.errors:

dataface/agent_api/project_session.py

@@ -144,6 +144,37 @@ class ProjectSession:
         session._resolver = resolver
         return session
 
+    @classmethod
+    def from_project(
+        cls,
+        project: Project,
+        *,
+        cache: DuckDBCache | None = None,
+        read_only: bool = True,
+        dbt_project_path: Path | None = None,
+        connection_string: str | None = None,
+        dialect: str = "duckdb",
+        target: str = "dev",
+        duckdb_config: dict[str, Any] | None = None,
+        allow_external_access_in_readonly: bool = False,
+        resolver: SourceResolver | None = None,
+    ) -> Self:
+        """Construct a ProjectSession from a pre-built Project.
+
+        Use this when the caller already holds a ``project: Project`` and does
+        not want to re-resolve the path.  The caller owns the Project lifecycle;
+        this method stores it directly without re-wrapping.
+        """
+        session = cls(project=project, cache=cache, read_only=read_only)
+        session._dbt_project_path = dbt_project_path
+        session._connection_string = connection_string
+        session._dialect = dialect
+        session._target = target
+        session._duckdb_config = duckdb_config
+        session._allow_external_access_in_readonly = allow_external_access_in_readonly
+        session._resolver = resolver
+        return session
+
     @classmethod
     def from_face(
         cls,
@@ -177,8 +208,7 @@ class ProjectSession:
         When constructed with an injected registry, returns it directly.
         """
         return build_adapter_registry(
-            self.project.root,
-            project_sources=self.project.sources,
+            self.project,
             read_only=self._read_only,
             dbt_project_path=self._dbt_project_path,
             connection_string=self._connection_string,
@@ -246,12 +276,12 @@ class ProjectSession:
     # ── Verb forwarders ──────────────────────────────────────────────────────
 
     def validate(self, face_path: Path) -> ValidateResult:
-        result = _validate.validate(face_path, project_dir=self.project.root)
+        result = _validate.validate(face_path, project=self.project)
         annotated = _validate.annotate_with_data_lint([result], project_session=self)
         return annotated[0]
 
     def validate_paths(self, paths: list[Path] | None) -> list[ValidateResult]:
-        results = _validate.validate_paths(paths, project_dir=self.project.root)
+        results = _validate.validate_paths(paths, project=self.project)
         return _validate.annotate_with_data_lint(results, project_session=self)
 
     def _source_names(self) -> frozenset[str]:
@@ -313,10 +343,10 @@ class ProjectSession:
         )
 
     def describe_face(self, path: Path) -> _describe.DescribeFaceResult:
-        return _describe.describe_face(path, project_dir=self.project.root)
+        return _describe.describe_face(path, project=self.project)
 
     def describe_paths(self, paths: list[Path]) -> list[_describe.DescribeFaceResult]:
-        return _describe.describe_paths(paths, project_dir=self.project.root)
+        return _describe.describe_paths(paths, project=self.project)
 
     def list_dashboards(
         self,
@@ -335,7 +365,7 @@ class ProjectSession:
         include_raw: bool = False,
     ) -> _dashboards.CompiledDashboard:
         return _dashboards.get_dashboard(
-            path, include_raw=include_raw, project_dir=self.project.root
+            path, include_raw=include_raw, project=self.project
         )
 
     def lookup_face_query_sql(
@@ -343,9 +373,7 @@ class ProjectSession:
         name: str,
         path: Path,
     ) -> _query.FaceQueryLookupResult:
-        return _query.lookup_face_query_sql(
-            name=name, path=path, project_dir=self.project.root
-        )
+        return _query.lookup_face_query_sql(name=name, path=path, project=self.project)
 
     def query_face(
         self,
@@ -357,7 +385,7 @@ class ProjectSession:
         return _query.query_face(
             name,
             path,
-            project_dir=self.project.root,
+            project=self.project,
             vars=vars,
             limit=limit,
             adapter_registry=self.adapter_registry,
@@ -412,7 +440,6 @@ class ProjectSession:
             yaml_content=yaml_content,
             variables=variables,
             adapter_registry=self.adapter_registry,
-            project_dir=self.project.root,
             project=self.project,
             duckdb_cache=self.cache,
             format=format,
@@ -422,7 +449,6 @@ class ProjectSession:
             scale=scale,
             ignore_codes=ignore_codes,
             max_workers=max_workers,
-            warnings_ignore=self.warnings_ignore,
             link_context=link_context,
             **render_options,
         )

dataface/agent_api/query.py

@@ -10,6 +10,7 @@ from dataface.core.compile import compile_file
 from dataface.core.compile.models.query.normalized import SqlQuery
 from dataface.core.execute.adapters import AdapterRegistry
 from dataface.core.inspect.query_validator import validate_query
+from dataface.core.project import Project
 from dataface.core.validate import normalize_data_for_json
 
 MAX_QUERY_LIMIT = 1000
@@ -29,7 +30,7 @@ def lookup_face_query_sql(
     name: str,
     path: Path,
     *,
-    project_dir: Path,
+    project: Project,
 ) -> FaceQueryLookupResult:
     """Compile a face file and extract the SQL + source for one named SQL query.
 
@@ -37,7 +38,7 @@ def lookup_face_query_sql(
     executing it against a warehouse.
     """
     try:
-        file_path = resolve_scoped_path(path, project_dir)
+        file_path = resolve_scoped_path(path, project.root)
     except ValueError as e:
         return FaceQueryLookupResult(success=False, errors=[str(e)])
 
@@ -46,7 +47,7 @@ def lookup_face_query_sql(
             success=False, errors=[f"File not found: {file_path}"]
         )
 
-    compile_result = compile_file(file_path)
+    compile_result = compile_file(file_path, project=project)
     if not compile_result.success:
         return FaceQueryLookupResult(
             success=False, errors=[e.message for e in compile_result.errors]
@@ -248,7 +249,7 @@ def _fail(
 def query_face(
     name: str,
     path: Path,
-    project_dir: Path | None = None,
+    project: Project,
     vars: dict[str, Any] | None = None,
     limit: int = 20,
     *,
@@ -258,17 +259,17 @@ def query_face(
     limit = min(limit, MAX_QUERY_LIMIT)
 
     try:
-        file_path = resolve_scoped_path(path, project_dir)
+        file_path = resolve_scoped_path(path, project.root)
     except ValueError as e:
         return _fail(name, path, [str(e)])
 
     if not file_path.exists():
         from dataface.agent_api._paths import no_project_hint
 
-        hint = no_project_hint(project_dir)
+        hint = no_project_hint(project.root)
         return _fail(name, file_path, [f"File not found: {file_path}{hint}"])
 
-    compile_result = compile_file(file_path)
+    compile_result = compile_file(file_path, project=project)
     if not compile_result.success:
         return _fail(name, file_path, [e.message for e in compile_result.errors])