{"id":29593122,"url":"https://github.com/berkeleybop/contextualizer","last_synced_at":"2025-07-20T06:34:44.533Z","repository":{"id":283349782,"uuid":"951487028","full_name":"berkeleybop/contextualizer","owner":"berkeleybop","description":null,"archived":false,"fork":false,"pushed_at":"2025-05-16T21:33:53.000Z","size":337,"stargazers_count":1,"open_issues_count":6,"forks_count":3,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-07-13T07:39:20.031Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/berkeleybop.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-03-19T18:54:10.000Z","updated_at":"2025-05-22T18:28:29.000Z","dependencies_parsed_at":"2025-05-03T03:19:50.944Z","dependency_job_id":"3d632973-987d-435a-8dde-fdb58d57796f","html_url":"https://github.com/berkeleybop/contextualizer","commit_stats":null,"previous_names":["cmungall/agent-test","cmungall/contextualizer","berkeleybop/contextualizer"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/berkeleybop/contextualizer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/berkeleybop%2Fcontextualizer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/berkeleybop%2Fcontextualizer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/berkeleybop%2Fcontextualizer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/berkeleybop%2Fcontextualizer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/berkeleybop","download_url":"https://codeload.github.com/berkeleybop/contextualizer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/berkeleybop%2Fcontextualizer/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266076552,"owners_count":23872777,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-07-20T06:34:42.822Z","updated_at":"2025-07-20T06:34:44.517Z","avatar_url":"https://github.com/berkeleybop.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Contextualizer Project: Comprehensive Guide\n\n## Project Overview\n\nThe Contextualizer project is an AI agent framework built on `pydantic-ai` that uses the Berkeley Lab's CBORG API to\naccess various language models. This guide combines official documentation, notes, and practical experience to help you\nget started with the project.\n\n## Prerequisites\n\n- Python 3.10+ installed (3.10+ is specified in pyproject.toml)\n- `uv` installed (a faster alternative to pip)\n- CBORG API key (required for all agents)\n- Google Maps API key (only required for map functionality in geo_agent.py)\n- python-dotenv package (installed automatically as a dependency)\n\n## 1. Understanding The CBORG API\n\n### What is CBORG?\n\nCBORG is Berkeley Lab's AI Portal that provides secure access to various AI models. The CBORG API server is an\nOpenAI-compatible proxy server built on LiteLLM, which means it can be used as a drop-in replacement for OpenAI's API.\n\n### Available Models\n\nThe CBORG API provides access to various models. Based on testing, your account may have access to:\n\n- **LBL-hosted models**:\n    - lbl/cborg-chat:latest\n    - lbl/cborg-vision:latest\n    - lbl/nomic-embed-text\n\n- **Commercial models**:\n    - openai/gpt-4.1-nano\n    - aws/claude-haiku\n    - (potentially others)\n\nNote that not all models listed in documentation may be available to your specific API key. You can use the test\nconnection script below to see which models are accessible to you.\n\n## 2. Environment Setup\n\n### Install UV\n\n```bash\n# Install UV on Unix/macOS\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Add to PATH if needed\n```\n\n### Create Virtual Environment\n\n```bash\n# Navigate to your repository\ncd contextualizer\n\n# Create a virtual environment with UV\nuv venv\n\n# Activate the virtual environment\nsource .venv/bin/activate\n\n# Install development dependencies\nuv pip install -e .\n```\n\n### Python Version Issues\n\nThe project requires Python 3.10+. If you're using pyenv and encounter version issues:\n\n```bash\n# Install Python 3.10 with pyenv\npyenv install 3.10\n\n# Or remove .python-version file to use UV's Python directly\nrm .python-version\n```\n\n## 3. API Key Configuration\n\n### Set Up Your CBORG API Key\n\nYou have several options:\n\n1. **Create a .env file** (recommended):\n   ```bash\n   echo \"CBORG_API_KEY=your_cborg_api_key_here\n   GOOGLE_MAPS_API_KEY=your_google_maps_api_key_here\" \u003e .env\n   ```\n   \n   The project uses python-dotenv to load environment variables from this file.\n\n2. **Export in your shell**:\n   ```bash\n   export CBORG_API_KEY=\"your_cborg_api_key_here\"\n   export GOOGLE_MAPS_API_KEY=\"your_google_maps_api_key_here\"  # Only if using map functions\n   ```\n\n3. **Use the .venv/bin/python approach**:\n   ```bash\n   CBORG_API_KEY=\"your_cborg_api_key_here\" .venv/bin/python your_script.py\n   ```\n\n### How to Get the CBORG API Key\n\n- If affiliated with Berkeley Lab: CBORG is free for employees with @lbl.gov, @es.net, or @nersc.gov email.\n\n## 4. Running Agents\n\nYou can run any of the agents using the Makefile:\n\n```bash\n# Run the hello world example\nmake hello-world\n\n# Run the geo agent\nmake geo\n\n# Run the soil agent\nmake soil\n\n# Run the weather agent\nmake weather\n\n# Run the Wikipedia animal QA agent\nmake wiki\n```\n\n## 5. Understanding and Using Agents\n\n### Common Agent Structure\n\nMost agents in this repository follow this pattern:\n\n1. Load environment variables and API key (using python-dotenv)\n2. Configure an AI model with the CBORG provider\n3. Create an Agent with a system prompt\n4. Register tools using decorators\n5. Execute queries with the agent\n\n### Agent Tools\n\nTools can be defined and registered using the `@agent.tool_plain` decorator, as shown in geo_agent.py:\n\n```python\n@geo_agent.tool_plain\ndef get_elev(\n        lat: float, lon: float,\n) -\u003e float:\n    \"\"\"\n    Get the elevation of a location.\n\n    :param lat: latitude\n    :param lon: longitude\n    :return: elevation in m\n    \"\"\"\n    print(f\"Looking up elevation for lat={lat}, lon={lon}\")\n    return elevation((lat, lon))\n```\n\n### Available Agents\n\n- **hello_world.py**: Simple \"Hello World\" example agent\n- **geo_agent.py**: Geographic data agent (needs GOOGLE_MAPS_API_KEY for map functionality)\n- **soil_agent.py**: Soil science agent\n- **weather.at.py**: Weather information agent\n- **wikipedia_animal_qa.py**: Wikipedia animal information agent\n- **evelation_info.py**: Tool for elevation information (used by geo_agent)\n\n## 7. Troubleshooting\n\n### Module Not Found Errors\n\nIf you see errors like: `ModuleNotFoundError: No module named 'agent_test'`:\n\n1. Use the virtual environment Python directly (as configured in the Makefile):\n   ```bash\n   .venv/bin/python -m pytest tests/\n   # or use the Makefile targets\n   make test-agent\n   make test-minimal\n   ```\n\n2. Or make sure you've activated the virtual environment:\n   ```bash\n   source .venv/bin/activate\n   pytest tests/\n   ```\n\n### API Key Authentication Errors\n\nIf your CBORG API key isn't being loaded:\n\n1. Check that your `.env` file exists and contains the correct key\n2. Verify that python-dotenv is installed (it should be installed automatically with dependencies)\n3. Ensure the .env file is in the root directory of the project\n\n### Model Availability Errors\n\nIf you see errors related to model availability:\n\n1. Update your agent code to use an available model (like \"lbl/cborg-chat:latest\")\n2. Check the error message for specific details about the failure\n\n## 8. Running Tests\n\nThe repository includes tests in the `tests/` directory with corresponding targets in the `Makefile`:\n\n```bash\n# Run all tests\nmake test-agent test-minimal\n\n# Run specific tests\nmake test-agent\nmake test-minimal\n```\n\nThe Makefile uses `.venv/bin/pytest` to ensure the correct Python environment is used.\n\nFor more reliable testing, you can also run tests directly:\n\n```bash\n.venv/bin/pytest tests/test_agent.py -v\n.venv/bin/pytest tests/test_minimal_agent.py -v\n```\n\n## 9. Code Style Guidelines\n\nThe project follows these coding standards:\n\n- **Imports**: Standard grouping (stdlib, third-party, local)\n- **Type Annotations**: All functions should use Python type hints\n- **Docstrings**: Multi-line docstring with params/returns (triple quotes)\n- **Naming**: snake_case for variables/functions, PascalCase for classes\n- **Error Handling**: Use try/except with logging, avoid silent failures\n- **Tools**: Use @agent.tool_plain decorator for agent functions\n- **Async**: Both sync and async functions are used; choose appropriately\n\n## 10. If You Don't Have Berkeley Lab Access\n\nIf you're not affiliated with Berkeley Lab and can't get a CBORG API key, you can modify the repository to use other LLM\nproviders:\n\n1. Change the base_url to your preferred provider\n2. Update the model names to ones available on that provider\n3. Adjust the API authentication methods as needed\n\nExample for using OpenAI directly:\n\n```python\nai_model = OpenAIModel(\n    \"gpt-4-turbo\",  # Use your available model\n    provider=OpenAIProvider(\n        api_key=os.getenv(\"OPENAI_API_KEY\")),  # No need for base_url with direct OpenAI\n)\n```\n\n## References and Resources\n\n- CBORG API Portal: https://cborg.lbl.gov/\n- API Documentation: https://cborg.lbl.gov/api_docs/\n- API Examples: https://cborg.lbl.gov/api_examples/\n- Pydantic-AI: Framework for building AI agents used by this project\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fberkeleybop%2Fcontextualizer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fberkeleybop%2Fcontextualizer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fberkeleybop%2Fcontextualizer/lists"}