# FAR Search Tool for LangChain

[![PyPI version](https://badge.fury.io/py/far-search-tool.svg)](https://pypi.org/project/far-search-tool/)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![LangChain](https://img.shields.io/badge/LangChain-Tool-green.svg)](https://python.langchain.com/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A **LangChain tool** for semantic search over **Federal Acquisition Regulations (FAR)**.

Enable your AI agents to search and understand U.S. government contracting regulations, procurement rules, and compliance requirements.

**Keywords**: langchain, government contracting, FAR, federal acquisition regulations, procurement, compliance, AI agent tools, RAG, semantic search

## Installation

```bash
pip install far-search-tool
```

## Quick Start

### Basic Usage (Free Tier)

```python
from far_search import FARSearchTool

# Initialize the tool
tool = FARSearchTool()

# Search FAR regulations
result = tool.invoke({
    "query": "small business set aside requirements",
    "top_k": 5
})

print(result)
```

### With RapidAPI Key (Higher Limits)

For production use with higher rate limits, get an API key from [RapidAPI](https://rapidapi.com/yschang/api/far-rag-federal-acquisition-regulation-search).

```python
from far_search import FARSearchTool

tool = FARSearchTool(rapidapi_key="your-rapidapi-key")

result = tool.invoke({
    "query": "cybersecurity requirements for contractors"
})
```

### Use with LangChain Agents

```python
from langchain.agents import initialize_agent, AgentType
from langchain_openai import ChatOpenAI
from far_search import FARSearchTool

# Initialize LLM and tool
llm = ChatOpenAI(model="gpt-4")
tools = [FARSearchTool()]

# Create agent
agent = initialize_agent(
    tools=tools,
    llm=llm,
    agent=AgentType.OPENAI_FUNCTIONS,
    verbose=True
)

# Ask about regulations
response = agent.run(
    "What are the FAR requirements for small business subcontracting plans?"
)
print(response)
```

### Use with LangGraph

```python
from langgraph.prebuilt import create_react_agent
from langchain_openai import ChatOpenAI
from far_search import FARSearchTool

# Create agent with FAR search capability
agent = create_react_agent(
    ChatOpenAI(model="gpt-4"),
    tools=[FARSearchTool()]
)

# Query the agent
result = agent.invoke({
    "messages": [("user", "What cybersecurity clauses should I include in a DoD contract?")]
})
```

## Features

- **Semantic Search**: Find relevant regulations using natural language queries
- **Pre-vectorized Data**: 617 FAR clauses with pre-computed embeddings for fast search
- **LLM-Optimized Output**: Results formatted for easy consumption by language models
- **Retry Logic**: Built-in handling for transient failures
- **Dual API Support**: Free tier or RapidAPI for production use

## API Reference

### FARSearchTool

```python
FARSearchTool(
    rapidapi_key: str = None,      # Optional RapidAPI key for paid tier
    base_url: str = None,          # Override API URL (for self-hosted)
    timeout: int = 30,             # Request timeout in seconds
    max_retries: int = 2           # Retry attempts on failure
)
```

### Input Schema

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `query` | str | required | Natural language search query |
| `top_k` | int | 5 | Number of results (1-20) |

### Output

Returns a formatted string containing matching FAR clauses with:
- Clause ID and title
- Relevance score
- Source reference
- URL to official documentation
- Clause text (truncated if long)

## Example Queries

- "Small business set aside requirements"
- "Cybersecurity contract clauses"
- "Payment terms for government contracts"
- "Contractor ethics and conduct rules"
- "Cost accounting standards"
- "Intellectual property rights in contracts"
- "Subcontracting plan requirements"
- "Contract termination procedures"

## Pricing

| Tier | Rate Limit | Price |
|------|------------|-------|
| Free | 500 requests/month | $0 |
| Pro | 5,000 requests/month | $29/month |
| Ultra | 150,000 requests/month | $199/month |

Get your API key at [RapidAPI](https://rapidapi.com/yschang/api/far-rag-federal-acquisition-regulation-search).

## Error Handling

```python
from far_search import FARSearchTool, FARAPIError, FARRateLimitError

tool = FARSearchTool()

try:
    result = tool.invoke({"query": "my query"})
except FARRateLimitError:
    print("Rate limit exceeded. Upgrade your plan or wait.")
except FARAPIError as e:
    print(f"API error: {e}")
```

## Compliance & Audit Logging

For government contractors and regulated industries, maintain audit trails of all FAR searches using [Agent Observability](https://pypi.org/project/agent-observability/):

```python
from far_search import FARSearchTool
from agent_observability import AgentLogger

# Initialize - auto-registers on first use, no API key needed!
far_tool = FARSearchTool()
logger = AgentLogger()

# Search and log for compliance
query = "cybersecurity requirements FAR 52.204"
results = far_tool.invoke({"query": query})

# Log the search for audit trail
logger.log("far_search", {
    "query": query,
    "results_count": len(results) if isinstance(results, list) else 1,
    "contract": "GS-00F-0001X",
    "purpose": "compliance_check"
})

# First log auto-registers and shows:
# ✅ Agent Observability - Auto-registered!
# 📋 Your API key: ao_live_abc123...
```

**Why log FAR searches?**

- **DFARS Compliance**: Government contracts often require audit trails
- **Cost Tracking**: Know how much time is spent on regulatory research
- **Team Analytics**: See what your team searches most frequently
- **SOC 2 / ISO 27001**: Demonstrate due diligence in compliance

**Setup (30 seconds):**

```bash
pip install agent-observability
```

That's it! No API key needed - auto-registers on first use. **Free tier: 100K logs/month.**

Learn more: [Agent Observability](https://github.com/blueskylineassets/agent-observability)

## Requirements

- Python 3.9+
- langchain >= 0.1.0
- requests >= 2.28.0
- pydantic >= 2.0.0

## License

MIT License - see [LICENSE](LICENSE) for details.

## Links

- [API Documentation](https://rapidapi.com/yschang/api/far-rag-federal-acquisition-regulation-search)
- [GitHub Repository](https://github.com/blueskylineassets/far-search-tool)
- [FAR Official Website](https://www.acquisition.gov/browse/index/far)

## Contributing

Contributions welcome! Please open an issue or submit a pull request.

