docent-python 0.1.0a1__tar.gz

docent_python-0.1.0a1/.gitignore

@@ -0,0 +1,192 @@
+**/*_gitignore.*
+**/*_gitignore/
+*.db
+.stignore
+*syncthing*
+.DS_Store
+# *.sql  (neil: disabled for ursid)
+*.gz
+
+*.tfstate
+*.tfstate.backup
+*/.terraform/
+*/*.terraform.*
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# wandb
+**/wandb/
+
+# Marimo notebook outputs
+**/__marimo__/
+
+# yarn
+**/.yarn/
+**/.pnp.*
+
+# data
+*.npy
+*.csv
+*.pkl
+*.eval
+
+# personal
+personal/caden/*
+inspect_evals

docent_python-0.1.0a1/LICENSE.md

@@ -0,0 +1,7 @@
+Copyright 2025 Clarity AI Research, Inc. dba Transluce
+
+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.

docent_python-0.1.0a1/PKG-INFO

@@ -0,0 +1,16 @@
+Metadata-Version: 2.4
+Name: docent-python
+Version: 0.1.0a1
+Summary: Docent SDK
+Project-URL: Homepage, https://github.com/TransluceAI/docent
+Project-URL: Issues, https://github.com/TransluceAI/docent/issues
+Project-URL: Docs, https://transluce-docent.readthedocs-hosted.com/en/latest
+Author-email: Transluce AI <info@transluce.org>
+License-Expression: MIT
+License-File: LICENSE.md
+Requires-Python: >=3.11
+Requires-Dist: logging>=0.4.9.6
+Requires-Dist: pydantic>=2.11.7
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: sqlalchemy>=2.0.41
+Requires-Dist: tiktoken>=0.7.0

docent_python-0.1.0a1/docent/__init__.py

@@ -0,0 +1,3 @@
+__all__ = ["Docent"]
+
+from docent.sdk.client import Docent

docent_python-0.1.0a1/docent/_log_util/__init__.py

@@ -0,0 +1,3 @@
+__all__ = ["get_logger"]
+
+from docent._log_util.logger import get_logger

docent_python-0.1.0a1/docent/_log_util/logger.py

@@ -0,0 +1,141 @@
+import logging
+import sys
+from dataclasses import dataclass
+from typing import Any, Dict, Literal, MutableMapping, Optional, Tuple
+
+
+@dataclass
+class ColorCode:
+    fore: str
+    style: str = ""
+
+
+class Colors:
+    # Foreground colors
+    BLACK = ColorCode("\033[30m")
+    RED = ColorCode("\033[31m")
+    GREEN = ColorCode("\033[32m")
+    YELLOW = ColorCode("\033[33m")
+    BLUE = ColorCode("\033[34m")
+    MAGENTA = ColorCode("\033[35m")
+    CYAN = ColorCode("\033[36m")
+    WHITE = ColorCode("\033[37m")
+    BRIGHT_MAGENTA = ColorCode("\033[95m")
+    BRIGHT_CYAN = ColorCode("\033[96m")
+
+    # Styles
+    BOLD = "\033[1m"
+    RESET = "\033[0m"
+
+    @staticmethod
+    def apply(text: str, color: ColorCode) -> str:
+        return f"{color.style}{color.fore}{text}{Colors.RESET}"
+
+
+class ColoredFormatter(logging.Formatter):
+    COLORS: Dict[int, ColorCode] = {
+        logging.DEBUG: Colors.BLUE,
+        logging.INFO: Colors.GREEN,
+        logging.WARNING: Colors.YELLOW,
+        logging.ERROR: Colors.RED,
+        logging.CRITICAL: ColorCode("\033[31m", Colors.BOLD),
+    }
+
+    # Available highlight colors
+    HIGHLIGHT_COLORS: Dict[str, ColorCode] = {
+        "magenta": ColorCode(Colors.BRIGHT_MAGENTA.fore, Colors.BOLD),
+        "cyan": ColorCode(Colors.BRIGHT_CYAN.fore, Colors.BOLD),
+        "yellow": ColorCode(Colors.YELLOW.fore, Colors.BOLD),
+        "red": ColorCode(Colors.RED.fore, Colors.BOLD),
+    }
+
+    def __init__(self, fmt: Optional[str] = None) -> None:
+        super().__init__(
+            fmt or "%(asctime)s [%(levelname)s] %(namespace)s: %(message)s", datefmt="%H:%M:%S"
+        )
+
+    def format(self, record: logging.LogRecord) -> str:
+        # Add namespace to extra fields if not present
+        if not getattr(record, "namespace", None):
+            record.__dict__["namespace"] = record.name
+
+        # Color the level name
+        record.levelname = Colors.apply(record.levelname, self.COLORS[record.levelno])
+
+        # Color the namespace
+        record.__dict__["namespace"] = Colors.apply(record.__dict__["namespace"], Colors.CYAN)
+
+        # Check if highlight flag is set
+        highlight = getattr(record, "highlight", None)
+        if highlight:
+            # Get the highlight color or default to magenta
+            color_name = highlight if isinstance(highlight, str) else "magenta"
+            highlight_color = self.HIGHLIGHT_COLORS.get(
+                color_name, self.HIGHLIGHT_COLORS["magenta"]
+            )
+
+            # Apply highlight to the message
+            original_message = record.getMessage()
+            record.msg = Colors.apply(original_message, highlight_color)
+            if record.args:
+                record.args = ()
+
+        return super().format(record)
+
+
+class LoggerAdapter(logging.LoggerAdapter[logging.Logger]):
+    """
+    Logger adapter that allows highlighting specific log messages.
+    """
+
+    def process(
+        self, msg: Any, kwargs: MutableMapping[str, Any]
+    ) -> Tuple[Any, MutableMapping[str, Any]]:
+        # Pass highlight flag through to the record
+        return msg, kwargs
+
+    def highlight(
+        self,
+        msg: object,
+        *args: Any,
+        color: Literal["magenta", "cyan", "yellow", "red", "green"] = "magenta",
+        **kwargs: Any,
+    ) -> None:
+        """
+        Log a highlighted message.
+
+        Args:
+            msg: The message format string
+            color: The color to highlight with (magenta, cyan, yellow, red)
+            *args: The args for the message format string
+            **kwargs: Additional logging kwargs
+        """
+        kwargs.setdefault("extra", {})
+        if isinstance(kwargs["extra"], dict):
+            kwargs["extra"]["highlight"] = color
+        return self.info(msg, *args, **kwargs)
+
+
+def get_logger(namespace: str) -> LoggerAdapter:
+    """
+    Get a colored logger for the specified namespace.
+
+    Args:
+        namespace: The namespace for the logger
+
+    Returns:
+        A configured logger instance with highlighting support
+    """
+    logger = logging.getLogger(namespace)
+
+    # Only add handler if it doesn't exist
+    if not logger.handlers:
+        handler = logging.StreamHandler(sys.stdout)
+        handler.setFormatter(ColoredFormatter())
+        logger.addHandler(handler)
+
+        # Set default level to INFO
+        logger.setLevel(logging.INFO)
+
+    # Wrap with adapter to support highlighting
+    return LoggerAdapter(logger, {})

docent_python-0.1.0a1/docent/data_models/__init__.py

@@ -0,0 +1,25 @@
+from docent.data_models.agent_run import AgentRun
+from docent.data_models.citation import Citation
+from docent.data_models.filters import (
+    AgentRunIdFilter,
+    BaseFrameFilter,
+    ComplexFilter,
+    SearchResultPredicateFilter,
+)
+from docent.data_models.metadata import BaseAgentRunMetadata, BaseMetadata, FrameDimension
+from docent.data_models.regex import RegexSnippet
+from docent.data_models.transcript import Transcript
+
+__all__ = [
+    "AgentRun",
+    "Citation",
+    "RegexSnippet",
+    "AgentRunIdFilter",
+    "FrameDimension",
+    "BaseFrameFilter",
+    "SearchResultPredicateFilter",
+    "ComplexFilter",
+    "BaseAgentRunMetadata",
+    "BaseMetadata",
+    "Transcript",
+]

docent_python-0.1.0a1/docent/data_models/_tiktoken_util.py

@@ -0,0 +1,91 @@
+import tiktoken
+
+MAX_TOKENS = 100_000
+
+
+def get_token_count(text: str, model: str = "gpt-4") -> int:
+    """Get the number of tokens in a text under the GPT-4 tokenization scheme."""
+    encoding = tiktoken.encoding_for_model(model)
+    return len(encoding.encode(text))
+
+
+def truncate_to_token_limit(text: str, max_tokens: int, model: str = "gpt-4") -> str:
+    """Truncate text to stay within the specified token limit."""
+    encoding = tiktoken.encoding_for_model(model)
+    tokens = encoding.encode(text)
+
+    if len(tokens) <= max_tokens:
+        return text
+
+    return encoding.decode(tokens[:max_tokens])
+
+
+class MessageRange:
+    """A range of messages in a transcript. start is inclusive, end is exclusive."""
+
+    start: int
+    end: int
+    include_metadata: bool
+    num_tokens: int
+
+    def __init__(self, start: int, end: int, include_metadata: bool, num_tokens: int):
+        self.start = start
+        self.end = end
+        self.include_metadata = include_metadata
+        self.num_tokens = num_tokens
+
+
+def group_messages_into_ranges(
+    token_counts: list[int], metadata_tokens: int, max_tokens: int, margin: int = 50
+) -> list[MessageRange]:
+    """Split a list of messages + metadata into ranges that stay within the specified token limit.
+
+    Always tries to create ranges with metadata included, unless a single message + metadata is too long,
+    in which case you get a lone message with no metadata
+    """
+    ranges: list[MessageRange] = []
+    start_index = 0
+    running_token_count = 0
+
+    i = 0
+    while i < len(token_counts):
+        new_token_count = token_counts[i]
+        if running_token_count + new_token_count + metadata_tokens > max_tokens - margin:
+            if start_index == i:  # a single message + metadata is already too long
+                ranges.append(
+                    MessageRange(
+                        start=i, end=i + 1, include_metadata=False, num_tokens=new_token_count
+                    )
+                )
+                i += 1
+            else:
+                # add all messages from start_index to i-1, with metadata included
+                ranges.append(
+                    MessageRange(
+                        start=start_index,
+                        end=i,
+                        include_metadata=True,
+                        num_tokens=running_token_count + metadata_tokens,
+                    )
+                )
+            running_token_count = 0
+            start_index = i
+        else:
+            running_token_count += new_token_count
+            i += 1
+
+    if running_token_count > 0:
+        include_metadata = running_token_count + metadata_tokens < max_tokens - margin
+        num_tokens = (
+            running_token_count + metadata_tokens if include_metadata else running_token_count
+        )
+        ranges.append(
+            MessageRange(
+                start=start_index,
+                end=len(token_counts),
+                include_metadata=include_metadata,
+                num_tokens=num_tokens,
+            )
+        )
+
+    return ranges