{"id":31727173,"url":"https://github.com/gianpd/xa-func-tools","last_synced_at":"2026-04-16T01:33:30.701Z","repository":{"id":318148940,"uuid":"1066630959","full_name":"gianpd/xa-func-tools","owner":"gianpd","description":"a clean, educational agent framework for learning and prototyping","archived":false,"fork":false,"pushed_at":"2025-10-05T15:50:18.000Z","size":87,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-13T08:08:02.191Z","etag":null,"topics":["agentic-framework","agents","ai","cognitive-architecture","explainability-ai","loop"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gianpd.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-29T18:45:48.000Z","updated_at":"2025-10-05T15:50:21.000Z","dependencies_parsed_at":"2025-10-05T13:21:38.893Z","dependency_job_id":"27c53fea-5634-4059-bb7e-9b2bbadff3df","html_url":"https://github.com/gianpd/xa-func-tools","commit_stats":null,"previous_names":["gianpd/xa-func-tools"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/gianpd/xa-func-tools","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gianpd%2Fxa-func-tools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gianpd%2Fxa-func-tools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gianpd%2Fxa-func-tools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gianpd%2Fxa-func-tools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gianpd","download_url":"https://codeload.github.com/gianpd/xa-func-tools/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gianpd%2Fxa-func-tools/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31867711,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-15T15:24:51.572Z","status":"ssl_error","status_checked_at":"2026-04-15T15:24:39.138Z","response_time":63,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["agentic-framework","agents","ai","cognitive-architecture","explainability-ai","loop"],"created_at":"2025-10-09T06:18:53.530Z","updated_at":"2026-04-16T01:33:30.643Z","avatar_url":"https://github.com/gianpd.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# xa-func-tools\n\n[![Python Version](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org/downloads/)\n[![License](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/gianpd/xa-func-tools/blob/main/LICENSE)\n[![GitHub Stars](https://img.shields.io/github/stars/gianpd/xa-func-tools?style=social)](https://github.com/gianpd/xa-func-tools)\n[![GitHub Forks](https://img.shields.io/github/forks/gianpd/xa-func-tools?style=social)](https://github.com/gianpd/xa-func-tools/fork)\n\n\nA lightweight, transparent Python framework for building AI agents with function calling. Designed to make agent behavior debuggable and understandable.\n\n## What is this?\n\n**xa-func-tools** helps you build AI agents that can use tools—scrape websites, search the web, process documents, and more. It wraps OpenAI-compatible APIs with a focus on making agent decisions visible and traceable.\n\nIf you've worked with LangChain or AutoGen and wanted something simpler to understand and modify, this might be for you.\n\n## Why use it?\n\n**Transparency first:** Every agent action is logged with reasoning steps, metadata, and execution traces. When something goes wrong (and it will), you can see exactly what happened.\n\n**Security by default:** URL validation is mandatory before any web interaction. No accidental requests to random URLs.\n\n**Async-native:** Built for I/O-bound tasks like web scraping and API calls. No blocking operations holding up your agent loops.\n\n**Easy to extend:** Register any Python function as a tool. The framework handles JSON schema generation and function calling automatically.\n\n**Honest about limitations:** This isn't solving hallucinations or replacing production frameworks. It's a learning tool and prototyping environment that prioritizes clarity over features.\n\n## Core Features\n\n- **ReAct-style agent loop:** Agents think out loud before acting, making reasoning visible\n- **Built-in tools:** Web scraping (Playwright), document extraction (PDF/DOCX), ArXiv search, URL analysis, web/X search\n- **Comprehensive logging:** Timestamps, token estimates, error tracking, and post-run analysis reports\n- **Async context managers:** Clean resource handling for browser sessions and HTTP clients\n- **Rate limiting \u0026 retries:** Production-ready error handling for flaky APIs\n- **Configurable system prompts:** Customize agent behavior without touching core code\n\n## Quick Start\n\n```bash\ngit clone https://github.com/gianpd/xa-func-tools.git\ncd xa-func-tools\npip install -e .\nplaywright install  # Only if using browser tools\n```\n\nSet your API key:\n```bash\nexport OPENROUTER_API_KEY=\"your-key-here\"\n# Optional: export SERPAPI_KEY=\"your-key\" for web search\n```\n\nBasic example:\n```python\nimport asyncio\nfrom src.function_calling import FunctionCalling\nfrom src.function_calling.tools import WebScraper\n\nasync def main():\n    async with WebScraper() as scraper:\n        agent = FunctionCalling(model=\"qwen/qwen3-next-80b-a3b-thinking\", max_turns=5)\n        agent.register_tool(scraper.scrape_text)\n        \n        answer, log = await agent.run_async(\"What's on the front page of example.com?\")\n        print(answer)\n        print(f\"\\nAgent took {len(log)} turns\")\n\nasyncio.run(main())\n```\n\nCheck the `examples/` folder for more complex demos like multi-source research agents.\n\n## How It Works\n\n1. You create a `FunctionCalling` instance with an LLM model and system prompt\n2. Register tools (any Python function) using `register_tool()`\n3. Call `run_async()` with your prompt\n4. The agent loops: think → call tools → process results → repeat\n5. Returns final answer + full execution log\n\nEach loop iteration logs:\n- Agent's reasoning (\"thought\")\n- Which tool was called and with what arguments\n- Tool results (truncated if needed for token efficiency)\n- Errors, durations, token estimates\n\nThe log is structured JSON you can analyze programmatically.\n\n## What You Can Build\n\n- **Research assistants:** Gather and synthesize information from multiple sources\n- **Web automation:** Navigate sites, extract data, generate reports\n- **Document processors:** Batch analyze PDFs, papers, or articles\n- **Monitoring bots:** Track websites or feeds for specific content\n- **Custom agents:** Combine tools to solve your specific problems\n\n## Limitations (The Honest Part)\n\n- **No memory persistence yet:** State is lost between runs. Vector DB integration is on the roadmap.\n- **Single agent only:** No multi-agent orchestration or collaboration patterns.\n- **Basic error recovery:** Retries and logging, but no sophisticated failure strategies.\n- **Token management is manual:** You need to watch context windows yourself.\n- **Not production-tested at scale:** This is a learning/prototyping tool, not enterprise software.\n\n## Roadmap\n\nPlanned improvements:\n- Persistent memory with vector database support\n- Multi-agent coordination patterns\n- Web UI for monitoring and debugging\n- Benchmark suite comparing performance to other frameworks\n- More sophisticated error recovery strategies\n\nPRs and ideas welcome—see Contributing below.\n\n## Contributing\n\nThis project thrives on community input. Whether you're fixing a bug, adding a tool, or improving documentation, contributions are appreciated.\n\n**How to contribute:**\n1. Fork the repo\n2. Create a feature branch\n3. Make your changes (follow PEP 8)\n4. Add tests if applicable\n5. Submit a PR with clear description\n\n**Need ideas?** Check the Issues tab for open tasks or suggest your own improvements.\n\n## Philosophy\n\nAt the end of the day, agent frameworks are thin wrappers around LLM API calls. The value isn't in complexity—it's in making those calls transparent, safe, and easy to debug. That's what xa-func-tools tries to do.\n\nIf you want a production framework with every feature, use LangChain. If you want to understand how agents work and build something custom, start here.\n\n## License\n\nMIT © [gianpd](https://github.com/gianpd) and contributors.\n\nUse it, modify it, learn from it. That's what open source is for.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgianpd%2Fxa-func-tools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgianpd%2Fxa-func-tools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgianpd%2Fxa-func-tools/lists"}