Dev

.github/workflows/examples.yml

@@ -0,0 +1,76 @@
+name: Examples
+
+on:
+  push:
+    branches: [ main, dev ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  examples:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.11'
+
+    - name: Install failcore
+      run: |
+        python -m pip install --upgrade pip
+        pip install -e .
+        # Install optional dependencies for examples
+        pip install langchain-core || true
+        pip install mcp || true
+
+    - name: Check examples directory exists
+      run: |
+        if [ ! -d "examples" ]; then
+          echo "Examples directory not found, skipping examples validation"
+          exit 0
+        fi
+
+    - name: Validate example syntax
+      run: |
+        if [ -d "examples" ]; then
+          echo "Checking Python syntax in examples..."
+          find examples/ -name "*.py" -exec python -m py_compile {} \;
+          echo "All examples have valid Python syntax"
+        else
+          echo "No examples directory found, skipping validation"
+        fi
+
+    - name: Test basic examples (if they exist)
+      run: |
+        if [ -d "examples/basic" ]; then
+          echo "Testing basic examples..."
+          cd examples/basic/
+          for file in *.py; do
+            if [ -f "$file" ]; then
+              echo "Checking $file..."
+              python -c "import ast; ast.parse(open('$file').read())"
+            fi
+          done
+        else
+          echo "No basic examples found, skipping"
+        fi
+      continue-on-error: true  # Don't fail CI if examples have runtime issues
+
+    - name: Test security examples (if they exist)
+      run: |
+        if [ -d "examples/security" ]; then
+          echo "Testing security examples..."
+          cd examples/security/
+          for file in *.py; do
+            if [ -f "$file" ]; then
+              echo "Checking $file..."
+              python -c "import ast; ast.parse(open('$file').read())"
+            fi
+          done
+        else
+          echo "No security examples found, skipping"
+        fi
+      continue-on-error: true

.gitignore

@@ -1,6 +1,6 @@
 .failcore/
-tests/
-examples/
+_tests/
+_examples/
 .pylintrc
 
 # Python

README.md

@@ -6,6 +6,9 @@
 
 [![PyPI version](https://badge.fury.io/py/failcore.svg)](https://badge.fury.io/py/failcore)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![Tests](https://github.com/zi-ling/failcore/workflows/Tests/badge.svg)](https://github.com/zi-ling/failcore/actions/workflows/test.yml)
+[![Code Quality](https://github.com/zi-ling/failcore/workflows/Code%20Quality/badge.svg)](https://github.com/zi-ling/failcore/actions/workflows/quality.yml)
+[![Examples](https://github.com/zi-ling/failcore/workflows/Examples/badge.svg)](https://github.com/zi-ling/failcore/actions/workflows/examples.yml)
 
 **When your agent breaks, you don't need better prompts — you need a circuit breaker.**
 

README_ZH.md

@@ -6,6 +6,9 @@
 
 [![PyPI version](https://badge.fury.io/py/failcore.svg)](https://badge.fury.io/py/failcore)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![Tests](https://github.com/zi-ling/failcore/workflows/Tests/badge.svg)](https://github.com/zi-ling/failcore/actions/workflows/test.yml)
+[![Code Quality](https://github.com/zi-ling/failcore/workflows/Code%20Quality/badge.svg)](https://github.com/zi-ling/failcore/actions/workflows/quality.yml)
+[![Examples](https://github.com/zi-ling/failcore/workflows/Examples/badge.svg)](https://github.com/zi-ling/failcore/actions/workflows/examples.yml)
 
 **当 Agent 出问题时，你不需要更好的 Prompt ——你需要一个“断路器”。**
 

examples/README.md

@@ -0,0 +1,123 @@
+# FailCore Examples
+
+This directory contains practical examples demonstrating FailCore's capabilities.
+
+## Basic Examples
+
+### 1. SDK Usage Sample (`basic/sample_sdk.py`)
+The most basic FailCore SDK usage with `@guard()` decorator:
+- File operations with sandbox protection
+- Network requests with SSRF protection  
+- Pure function protection
+- Basic error handling
+
+```bash
+python examples/basic/sample_sdk.py
+```
+
+### 2. LangChain Integration (`basic/langchain_integration.py`)
+Zero-modification integration with LangChain tools:
+- Protect existing LangChain tools automatically
+- Batch protection for multiple tools
+- Preserve LangChain metadata and functionality
+- Full ecosystem compatibility
+
+```bash
+pip install langchain-core
+python examples/basic/langchain_integration.py
+```
+
+### 3. Proxy Mode (`basic/proxy_mode.py`)
+Zero-code integration using HTTP proxy:
+- Transparent interception of API calls
+- No application code changes needed
+- Real-time monitoring and security
+- Streaming response support
+
+```bash
+pip install httpx
+python examples/basic/proxy_mode.py
+```
+
+### 4. MCP Integration (`basic/mcp_mode.py`)
+Model Context Protocol (MCP) integration with FailCore:
+- Secure MCP server/client communication
+- Tool validation and security enforcement
+- Real-time monitoring of MCP interactions
+- Policy-based security for all MCP operations
+
+```bash
+python examples/basic/mcp_mode.py
+```
+
+## Running Examples
+
+All examples are self-contained and include:
+- Clear explanations of what they demonstrate
+- Expected output descriptions
+- Error handling examples
+- Cleanup procedures
+
+### Prerequisites
+
+Basic examples only require FailCore:
+```bash
+pip install failcore
+```
+
+Some examples have additional dependencies:
+```bash
+pip install langchain-core  # for LangChain integration
+pip install httpx          # for proxy mode examples
+```
+
+### Example Output
+
+Each example generates:
+- Console output showing security protections in action
+- Trace files for audit and debugging
+- Clear success/failure indicators
+
+### Viewing Results
+
+After running examples, you can:
+```bash
+# View the latest trace
+failcore show
+
+# Generate HTML report
+failcore report --last > report.html
+
+# List all runs
+failcore list
+```
+
+## Example Structure
+
+```
+examples/
+├── basic/                    # Basic usage examples
+│   ├── sample_sdk.py        # @guard() decorator basics
+│   ├── langchain_integration.py  # LangChain tool protection
+│   ├── proxy_mode.py        # HTTP proxy interception
+│   └── mcp_mode.py          # MCP integration example
+└── README.md               # This file
+```
+
+## Next Steps
+
+After trying these examples:
+
+1. **Explore Advanced Features**: Check the documentation for advanced policies, custom rules, and enterprise features
+
+2. **Integration**: Integrate FailCore into your existing AI agent applications
+
+3. **Production Deployment**: Use proxy mode for zero-code production deployment
+
+4. **Monitoring**: Set up continuous monitoring and alerting
+
+## Getting Help
+
+- **Documentation**: https://zi-ling.github.io/failcore/
+- **Issues**: https://github.com/zi-ling/failcore/issues
+- **Discussions**: https://github.com/zi-ling/failcore/discussions