From bcb4f7a3fb35badcce3a214c3f816c62807f15bc Mon Sep 17 00:00:00 2001
From: Jayakrishna Ichapurapu <jaykrishna316@users.noreply.github.com>
Date: Fri, 9 Oct 2026 18:38:49 -0500
Subject: [PATCH] feat: Add/update AGENTS.md for AI agent guidance

Generated by Braxis
https://github.com/jaykrishna316/braxis

Co-Authored-By: Jayakrishna Ichapurapu
---
 .agentic-config.json | 134 +++++++++++++++++++++++
 .cursorrules         |  77 +++++++++++++
 AGENTS.md            | 249 +++++++++++++++++++++++++++++++++++++++++++
 CLAUDE.md            |  53 +++++++++
 4 files changed, 513 insertions(+)
 create mode 100644 .agentic-config.json
 create mode 100644 .cursorrules
 create mode 100644 AGENTS.md
 create mode 100644 CLAUDE.md

diff --git a/.agentic-config.json b/.agentic-config.json
new file mode 100644
index 0000000..b13ef27
--- /dev/null
+++ b/.agentic-config.json
@@ -0,0 +1,134 @@
+{
+  "metadata": {
+    "project_name": "replicate-python",
+    "description": "A Python project with Python (setuptools)",
+    "generated_by": "Braxis",
+    "generated_at": "2026-10-09T18:38:49.160037",
+    "schema_version": "1.0"
+  },
+  "project": {
+    "languages": [
+      "python"
+    ],
+    "primary_language": "python",
+    "build_system": "Python (setuptools)",
+    "architecture": "single-package",
+    "is_monorepo": false,
+    "monorepo_type": null,
+    "subsystems": []
+  },
+  "ai_readiness": {
+    "overall_score": 68,
+    "tier": "AI-Native",
+    "dimensions": {
+      "architecture": {
+        "score": 0,
+        "reason": "Code organization and modularity"
+      },
+      "testing": {
+        "score": 15,
+        "reason": "52 test files found"
+      },
+      "dependencies": {
+        "score": 12,
+        "reason": "Dependency management and version pinning"
+      },
+      "conventions": {
+        "score": 8,
+        "reason": "Consistency in naming and patterns"
+      },
+      "entry_points": {
+        "score": 0,
+        "reason": "0 critical files identified"
+      },
+      "security": {
+        "score": 10,
+        "reason": "Input validation and error handling"
+      },
+      "build": {
+        "score": 10,
+        "reason": "Build system clarity and configuration"
+      },
+      "documentation": {
+        "score": 8,
+        "reason": "README and code documentation"
+      }
+    }
+  },
+  "development": {
+    "setup_command": "pip install -e . && uv sync --all-groups",
+    "test_command": "pytest",
+    "lint_command": "ruff check .",
+    "format_command": "ruff format .",
+    "dev_server_command": null,
+    "prerequisites": {
+      "language_version": "3.9+",
+      "package_manager": "pip or uv",
+      "key_tools": [
+        "pytest",
+        "ruff",
+        "mypy"
+      ]
+    }
+  },
+  "architecture": {
+    "pattern": "single-package project",
+    "main_entry": "Standard layout",
+    "key_modules": [],
+    "layers": [
+      "CLI interface (if applicable)",
+      "Business logic",
+      "Utilities and helpers"
+    ]
+  },
+  "mcp_servers": [],
+  "core_principles": [
+    "Modularity - Code organized by functionality",
+    "Testability - Comprehensive test coverage",
+    "Clarity - Code easy for AI agents to understand",
+    "Consistency - Uniform patterns throughout"
+  ],
+  "contribution_criteria": {
+    "what_we_want": [
+      "Bug fixes with test coverage",
+      "Code quality improvements",
+      "Test coverage increases",
+      "Documentation improvements",
+      "Performance optimizations"
+    ],
+    "what_we_dont_want": [
+      "New dependencies without justification",
+      "Code that reduces test coverage",
+      "Inconsistent naming or style",
+      "Dead code or commented code"
+    ]
+  },
+  "contribution_boundaries": {
+    "project_scale": "small",
+    "suggestion": "This small project can accept most contributions. Consider boundaries as it grows."
+  },
+  "commands": {
+    "setup": {
+      "command": "pip install -e . && uv sync --all-groups",
+      "description": "Install dependencies and set up development environment"
+    },
+    "test": {
+      "command": "pytest",
+      "description": "Run all tests"
+    },
+    "lint": {
+      "command": "ruff check .",
+      "description": "Check code style and quality"
+    },
+    "format": {
+      "command": "ruff format .",
+      "description": "Format code to project standards"
+    }
+  },
+  "testing": {
+    "framework": "pytest",
+    "total_tests": 52,
+    "pass_rate": 100,
+    "run_command": "pytest"
+  }
+}
\ No newline at end of file
diff --git a/.cursorrules b/.cursorrules
new file mode 100644
index 0000000..5c0ed35
--- /dev/null
+++ b/.cursorrules
@@ -0,0 +1,77 @@
+# Cursor Rules for replicate-python
+
+## What This Project Does
+
+**Language:** Python | **Build:** Python (setuptools)
+
+**AI Readiness Score:** 68/100 (AI-Native)
+
+## Must-Follow Rules
+
+### Code Style & Formatting
+
+1. Use **ruff** for formatting: `ruff format .`
+2. Use **ruff** for linting: `ruff check .`
+3. Python conventions: **snake_case** for functions/variables, **PascalCase** for classes
+4. Type hints: Required for all public functions using **mypy** for checking
+5. Docstrings: Use triple-quoted strings for all public functions and classes
+6. No commented-out code, no dead code
+7. Max line length: 100 characters
+
+### Testing
+1. Framework: pytest
+2. Test file naming: `test_*.py` or `*_test.py`
+3. Test discovery: `pytest` finds and runs all tests
+4. Fixtures: Use pytest fixtures for setup/teardown
+5. Coverage: Maintain 80%+ coverage for critical paths
+6. Run before commit: `pytest -v`
+
+### Imports & Dependencies
+1. Use absolute imports, not relative imports (unless necessary)
+2. Group imports: stdlib, third-party, local (isort style)
+3. No wildcard imports (`from module import *`)
+4. Pin versions in requirements.txt/pyproject.toml
+5. Avoid circular dependencies
+
+### Error Handling
+1. Be specific with exception types (not bare `except:`)
+2. Log errors before re-raising
+3. Validate all function arguments at entry points
+4. Use try/except at system boundaries (I/O, network, DB)
+
+
+## Scoring Dimensions (What Matters)
+
+These 8 areas drive AI readiness. Focus on these when making changes:
+
+1. **Architecture** (0/15) - Code organization and modularity
+2. **Testing** (15/15) - Test coverage and quality
+3. **Dependencies** (12/12) - Dependency management
+4. **Conventions** (8/10) - Consistent patterns
+5. **Entry Points** (0/10) - Clear main/start locations
+6. **Security** (10/15) - Input validation and error handling
+7. **Build** (10/10) - Clear build/setup instructions
+8. **Documentation** (8/8) - Code and project documentation
+
+## Before You Commit
+
+```bash
+# Format code
+ruff format .
+
+# Lint check
+ruff check .
+
+# Run tests
+pytest
+```
+
+All checks must pass before committing.
+
+## Questions?
+
+See AGENTS.md for detailed documentation on architecture, development workflow, and testing strategy.
+
+---
+
+*Generated by Braxis - language-aware rules for Python projects*
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..efa5f42
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,249 @@
+# AGENTS.md
+
+Context file for AI agents working on replicate-python.
+
+**Dual Format**: This file combines Category A (Operations Manual) and Category B (Context Guide) for comprehensive agent guidance.
+
+**Domain Detected:** Ml / Training (Based on codebase patterns)
+
+## Project Overview
+
+replicate-python is a Python project using Python (setuptools).
+
+**Key Info:**
+- **Primary Language:** Python
+- **Build System:** Python (setuptools)
+- **Test Framework:** pytest
+- **Total Files:** 88
+- **Test Files:** 52
+- **AI Readiness Score:** 68/100 (AI-Native)
+
+---
+
+## 🚨 AI Policy & Operations
+
+Extracted from CONTRIBUTING.md - operational constraints and procedures.
+
+### Key Requirements
+
+- `REPLICATE_API_TOKEN`: Required. Find your token at https://replicate.com/#token
+
+### Development Procedures
+
+- [How to sign off your commits](#how-to-sign-off-your-commits)
+- Each commit you contribute to this repo must be signed off (not to be confused with **[signing](https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work)**). It certifies that you wrote the patch, or have the right to contribute it. It is called the [Developer Certificate of Origin](https://developercertificate.org/) and was originally developed for the Linux kernel.
+- Then add this line to each of your Git commit messages, with your name and email:
+- If you're using the `git` CLI, you can sign a commit by passing the `-s` option: `git commit -s -m "Reticulate splines"`
+- You can also create a git hook which will sign off all your commits automatically. Using hooks also allows you to sign off commits when using non-command-line tools like GitHub Desktop or VS Code.
+
+
+
+## 🧠 Machine Learning Architecture
+
+This is a machine learning or model training system.
+
+### Key Components
+
+- **Data Pipeline:** Data loading, preprocessing, augmentation
+- **Model Definition:** Architecture, hyperparameters, checkpoints
+- **Training Loop:** Loss calculation, gradient updates, validation
+- **Inference:** Model predictions, batch processing, latency optimization
+- **Evaluation:** Metrics, benchmarks, comparison to baselines
+
+### Critical Areas
+
+1. **Data Leakage:** Ensure train/test/validation splits are isolated
+2. **Reproducibility:** Set random seeds; version datasets and models
+3. **Resource Management:** Monitor memory, GPU usage during training
+4. **Versioning:** Track model checkpoints, hyperparameters, and results
+5. **Evaluation Rigor:** Use proper metrics; avoid optimizing to test set
+
+### Testing Strategy
+
+- **Data Pipeline Tests:** Verify shape, type, and value ranges
+- **Model Tests:** Check predictions with synthetic/known inputs
+- **Training Tests:** Verify loss decreases on toy datasets
+- **Inference Tests:** Check latency and memory usage
+- **Regression Tests:** Compare results against baseline models
+
+
+
+### Detected Frameworks
+
+| Framework | Version | Detection Type |
+|-----------|---------|-----------------|
+| numpy | unknown | Direct import |
+| pydantic | latest | Direct import |
+| pytest | unknown | Direct import |
+| unittest | unknown | Direct import |
+
+
+
+## 🏗️ Architecture & Context Guide
+
+This section provides architectural context and agent-understanding for the codebase.
+
+### Prerequisites
+
+- **Python:** >=3.8 (or applicable language version)
+- **Package Manager:** pip or uv
+- **Test Runner:** pytest
+
+
+
+### Project Structure
+
+```
+replicate-python/
+├── pyproject.toml
+├── replicate/             # Source code
+├── tests/                # Test suite (52 files)
+└── README.md             # Project documentation
+```
+
+### Architecture Overview
+
+#### Key Components
+- **Main Entry:** Standard layout
+- **Test Suite:** 52 test files
+- **Build Configuration:** pyproject.toml
+
+#### Design Principles
+
+1. **Modularity** - Code organized by functionality with clear separation of concerns
+2. **Testability** - Comprehensive test coverage across critical paths
+3. **Clarity** - Explicit naming and structure for AI agent understanding
+4. **Consistency** - Uniform patterns and conventions throughout codebase
+5. **Maintainability** - Well-documented code with clear intent
+
+### Directory Map
+
+| Directory | Purpose |
+|-----------|----------|
+| `tests/` | Test suite |
+
+
+### Development Workflow
+
+#### Initial Setup
+
+```bash
+git clone https://github.com/replicate/replicate-python
+cd replicate-python
+pip install -e .
+# or
+uv sync --all-groups
+```
+
+#### Development Commands
+
+**Running Tests:**
+```bash
+pytest                    # Run all tests
+pytest tests/             # Run specific test directory
+pytest -v                 # Verbose output with test names
+pytest -x                 # Stop on first failure
+coverage run -m pytest && coverage report  # With coverage report
+```
+
+#### Code Quality
+```bash
+ruff check .              # Lint with ruff
+ruff format .             # Format code
+mypy .                    # Type checking (if configured)
+```
+
+### Code Style & Conventions
+
+- **Naming:** Use snake_case for functions and variables
+- **Type Hints:** Yes (strongly encouraged)
+- **Error Handling:** Yes - handle errors at boundaries; let exceptions propagate when another layer owns recovery
+- **Logging:** No
+- **Testing:** Yes - write tests alongside code changes
+
+### Testing Strategy
+
+**Framework:** pytest
+**Test Files:** 52 found
+
+Before committing:
+1. Run the full test suite: `pytest`
+2. Ensure all tests pass
+3. Check type hints: `mypy .`
+4. Format code: `ruff format .`
+
+### Writing Documentation
+
+When updating docs:
+1. Always include explanatory text before code snippets
+2. Describe *why* and *what* before showing *how*
+3. Keep sections focused on a single concept
+4. Use clear, concrete examples
+
+### Contributing Guidelines
+
+This project has a detailed contribution guide at **`CONTRIBUTING.md`**.
+
+**Key Requirements:**
+- **DCO Sign-off Required**: Every commit must be signed with `git commit -s`
+
+**Before submitting:**
+1. Read `CONTRIBUTING.md` in full
+2. Check recent merged PRs for patterns
+3. Follow the specific requirements above
+
+### Common Patterns
+
+When contributing to this project:
+1. Read existing code in the area you're modifying
+2. Follow the established patterns and style
+3. Write tests for new functionality
+4. Use clear, descriptive variable and function names
+5. Add docstrings for public APIs
+6. Update tests when changing behavior
+
+### What We Value
+
+✅ Well-tested code with clear intent
+✅ Consistent code style and naming conventions
+✅ Code that is easy for AI agents to understand
+✅ Clear, descriptive commit messages
+✅ Modular, reusable components
+✅ Comprehensive documentation
+
+### What We Avoid
+
+❌ Large functions doing multiple things
+❌ Commented-out dead code
+❌ Inconsistent naming or patterns
+❌ Unclear error messages
+❌ Unexplained magic numbers or strings
+❌ Skipped tests or test TODOs
+
+### AI Readiness Dimensions (Scoring)
+
+This project is evaluated across 8 dimensions:
+
+1. **Architecture** (0/100) - Code organization and modularity
+2. **Testing** (15/100) - Test coverage and quality
+3. **Dependencies** (12/100) - Dependency management
+4. **Conventions** (8/100) - Consistent patterns
+5. **Entry Points** (0/100) - Clear main/start locations
+6. **Security** (10/100) - Input validation and error handling
+7. **Build** (10/100) - Clear build/setup instructions
+8. **Documentation** (8/100) - Code and project documentation
+
+### Next Steps
+
+Before making changes:
+1. Read relevant source files to understand the existing code
+2. Look at existing tests for similar functionality
+3. Follow the patterns you see in the codebase
+4. Write tests for your changes
+5. Run `pytest` to verify nothing breaks
+6. Run code quality checks: `ruff check . && mypy .`
+7. Format your code: `ruff format .`
+
+---
+
+*Generated by Braxis - keeping AI agents in sync with your code*
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..2295b75
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,53 @@
+# CLAUDE.md
+
+@AGENTS.md
+
+This project uses AGENTS.md as the standard agent context. Claude Code loads it automatically via the @AGENTS.md import above.
+
+## Project: replicate-python
+
+**Language:** Python | **Build:** Python (setuptools) | **Score:** 68/100
+
+---
+
+## Project-Specific Caveats
+
+- if "(some known issue)" in e.prediction.logs:
+
+## Quick Reference for Claude
+
+### Before You Start
+1. **Read AGENTS.md first** for full project architecture and workflow
+2. **Check the caveats above** — they're extracted from this project's docs
+3. **Run tests locally** before suggesting code changes
+4. **Follow AGENTS.md conventions** for code style
+
+### Key Commands
+```bash
+# Regenerate AI context files
+braxis generate
+
+# View AI readiness score
+braxis score
+
+# See score trends
+braxis history --trends
+```
+
+### Testing Workflow
+```bash
+pytest
+```
+
+### Code Quality
+```bash
+ruff check .          # Lint
+ruff format .         # Format
+mypy .               # Type check
+```
+
+---
+
+See AGENTS.md for complete project documentation.
+
+*Generated by Braxis - keeping AI agents in sync with replicate-python*