contextagent 0.1.0__tar.gz

contextagent-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Zhimeng Guo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

contextagent-0.1.0/PKG-INFO

@@ -0,0 +1,269 @@
+Metadata-Version: 2.4
+Name: contextagent
+Version: 0.1.0
+Summary: A Research-Oriented Multi-Agent System Platform
+Author-email: Zhimeng Guo <gzjz07@outlook.com>
+License: MIT
+Project-URL: Homepage, https://github.com/TimeLovercc/agentz
+Project-URL: Repository, https://github.com/TimeLovercc/agentz
+Project-URL: Documentation, https://github.com/TimeLovercc/agentz#readme
+Project-URL: Bug Tracker, https://github.com/TimeLovercc/agentz/issues
+Keywords: agent,multi-agent,ai,llm,research,machine-learning,autonomous-agents
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: build>=1.3.0
+Requires-Dist: google-generativeai>=0.8.5
+Requires-Dist: ipdb>=0.13.13
+Requires-Dist: litellm==1.76
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: matplotlib>=3.10.6
+Requires-Dist: numpy>=2.3.3
+Requires-Dist: openai-agents>=0.3.2
+Requires-Dist: pandas>=2.3.3
+Requires-Dist: rich>=14.1.0
+Requires-Dist: scikit-learn>=1.7.2
+Requires-Dist: seaborn>=0.13.2
+Requires-Dist: twine>=6.2.0
+Requires-Dist: weave>=0.52.8
+Dynamic: license-file
+
+<div align="center">
+
+# AgentZ: Agent from Zero
+
+**A Research-Oriented Multi-Agent System Platform**
+
+</div>
+
+AgentZ is a minimal, extensible codebase for multi-agent systems research. Build intelligent agent workflows with minimal code while achieving strong baseline performance. The platform enables autonomous reasoning, experience learning, and dynamic tool creation - providing both a comparative baseline and production-ready foundation for multi-agent research.
+
+## Features
+
+- **🎯 Minimal Implementation** - Build new systems with just a few lines of code
+- **🔄 Stateful Workflows** - Persistent memory and object management throughout agent lifecycle
+- **📚 Experience Learning** - Agents improve over time through memory-based reasoning
+- **🛠️ Dynamic Tool Creation** - Agents can generate and use custom tools on-demand
+- **🧠 Autonomous Reasoning** - Built-in cognitive capabilities for complex multi-step tasks
+- **⚙️ Config-Driven** - Easily modify behavior through configuration files
+
+## Installation
+
+This project uses [uv](https://docs.astral.sh/uv/) for fast, reliable package management.
+
+### Install uv
+
+```bash
+# macOS/Linux
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Or via pip
+pip install uv
+```
+
+See the [uv installation guide](https://docs.astral.sh/uv/getting-started/installation/) for more options.
+
+### Setup Environment
+
+```bash
+# Clone the repository
+git clone https://github.com/yourusername/agentz.git
+cd agentz
+
+# Sync dependencies
+uv sync
+```
+
+## Quick Start
+
+```python
+from pipelines.data_scientist import DataScientistPipeline
+
+pipe = DataScientistPipeline("pipelines/configs/data_science.yaml")
+
+pipe.run_sync()
+```
+
+## Building Your Own System
+
+### 1. Create a Custom Pipeline
+
+Inherit from `BasePipeline` to create your own agent workflow:
+
+```python
+from pipelines.base import BasePipeline
+
+
+class MyCustomPipeline(BasePipeline):
+    DEFAULT_CONFIG_PATH = "pipelines/configs/my_pipeline.yaml"
+
+    def __init__(self, config=None):
+        super().__init__(config)
+        # Add your custom initialization
+
+    async def run(self):
+        # Implement your workflow logic
+        pass
+```
+
+### 2. Add Custom Agents
+
+Implement your agents following the standard interface:
+
+```python
+from agents import Agent
+
+def create_my_agent(config):
+    return Agent(
+        name="my_agent",
+        instructions="Your agent instructions here",
+        model=config.main_model
+    )
+```
+
+### 3. Configure & Run
+
+Create a config file and run your pipeline:
+
+```python
+pipe = MyCustomPipeline(
+    data_path="your_data.csv",
+    user_prompt="Your task description",
+    provider="gemini",
+    model="gemini-2.5-flash"
+)
+
+pipe.run_sync()
+```
+
+## Architecture
+
+AgentZ is organised around a **central conversation state** and a set of declarative
+flow specifications that describe how agents collaborate. The main
+components you will interact with are:
+
+- **`pipelines/`** – High level orchestration that wires agents together.
+- **`agentz/agents/`** – Capability definitions for manager agents and tool agents.
+- **`agentz/flow/`** – Flow primitives (`FlowRunner`, `FlowNode`, `IterationFlow`) that
+  execute declarative pipelines.
+- **`agentz/memory/`** – Structured state management (`ConversationState`,
+  `ToolExecutionResult`, global memory helpers).
+- **`examples/`** – Example scripts showing end-to-end usage.
+
+```
+agentz/
+├── pipelines/
+│   ├── base.py               # Base pipeline with config management & helpers
+│   ├── flow_runner.py        # Declarative flow executor utilities
+│   └── data_scientist.py     # Reference research pipeline
+├── agentz/
+│   ├── agents/
+│   │   ├── manager_agents/   # Observe, evaluate, routing, writer agents
+│   │   └── tool_agents/      # Specialised tool executors
+│   ├── flow/                 # Flow node definitions and runtime objects
+│   ├── memory/               # Conversation state & persistence utilities
+│   ├── llm/                  # LLM adapters and setup helpers
+│   └── tools/                # Built-in tools
+└── examples/
+    └── data_science.py       # Example workflows
+```
+
+### Declarative Pipeline Flow
+
+The reference `DataScientistPipeline` models an entire research workflow using
+three building blocks:
+
+1. **Central ConversationState** – A shared store that captures every field any
+   agent might read or write (iteration metadata, gaps, observations, tool
+   results, timing, final report, etc.). Each loop creates a new
+   `IterationRecord`, enabling partial updates and clean tracking of tool
+   outcomes.
+2. **Structured IO Contracts** – Each agent step declares the Pydantic model it
+   expects and produces (for example `KnowledgeGapOutput` or
+   `AgentSelectionPlan`). Input builders map slices of `ConversationState` into
+   those models and output handlers merge the validated results back into the
+   central state.
+3. **Declarative FlowRunner** – The pipeline defines an `IterationFlow` of
+   `FlowNode`s such as observe → evaluate → route → tools. Loop and termination
+   logic are expressed with predicates (`loop_condition`, `condition`), so the
+   executor can stop when evaluation marks `state.complete` or constraints are
+   reached. Finalisation steps (like the writer agent) run after the iteration
+   loop using the same structured IO.
+
+Because the flow is declarative and all state is centralised, extending the
+pipeline is as simple as adding a new node, output field, or tool capability—no
+custom `run()` logic is required beyond sequencing the flow runner.
+
+## Benchmarks
+
+AgentZ has been verified on several benchmarks for multi-agent research:
+
+- **Data Science Tasks**: State-of-the-art performance on automated ML pipelines
+- **Complex Reasoning**: Competitive results on multi-step reasoning benchmarks
+- **Tool Usage**: High accuracy in dynamic tool selection and execution
+
+*Detailed benchmark results and comparisons coming soon.*
+
+## Roadmap
+
+- [x] Persistence Process - Stateful agent workflows
+- [x] Experience Learning - Memory-based reasoning
+- [x] Tool Design - Dynamic tool creation
+- [ ] Workflow RAG - Retrieval-augmented generation for complex workflows
+- [ ] MCPs - Model Context Protocol support for enhanced agent communication
+
+## Key Design Principles
+
+1. **Minimal Core** - Keep the base system simple and extensible
+2. **Intelligent Defaults** - Provide strong baseline implementations
+3. **Research-First** - Design for experimentation and comparison
+4. **Modular Architecture** - Easy to swap components and test variations
+5. **Production-Ready** - Scale from research prototypes to deployed systems
+
+## Use Cases
+
+- **Multi-Agent Research** - Baseline for comparing agent architectures
+- **Automated Data Science** - End-to-end ML pipeline automation
+- **Complex Task Decomposition** - Break down and solve multi-step problems
+- **Tool-Using Agents** - Research on dynamic tool creation and usage
+- **Agent Memory Systems** - Study persistence and experience learning
+
+## Citation
+
+If you use AgentZ in your research, please cite:
+
+```bibtex
+@software{agentz2025,
+  title={AgentZ: A Research-Oriented Multi-Agent System Platform},
+  author={Your Name},
+  year={2025},
+  url={https://github.com/yourusername/agentz}
+}
+```
+
+## Contributing
+
+We welcome contributions! AgentZ is designed to be a community resource for multi-agent research. Please open an issue or submit a pull request.
+
+## License
+
+[Your License Here]
+
+## Acknowledgements
+
+AgentZ is built with inspiration from the multi-agent systems research community. We thank the developers of various LLM frameworks and tools that make this work possible.
+
+---
+
+<div align="center">
+
+**AgentZ**: Building intelligent agents from zero to hero 🚀
+
+</div>

contextagent-0.1.0/README.md

@@ -0,0 +1,232 @@
+<div align="center">
+
+# AgentZ: Agent from Zero
+
+**A Research-Oriented Multi-Agent System Platform**
+
+</div>
+
+AgentZ is a minimal, extensible codebase for multi-agent systems research. Build intelligent agent workflows with minimal code while achieving strong baseline performance. The platform enables autonomous reasoning, experience learning, and dynamic tool creation - providing both a comparative baseline and production-ready foundation for multi-agent research.
+
+## Features
+
+- **🎯 Minimal Implementation** - Build new systems with just a few lines of code
+- **🔄 Stateful Workflows** - Persistent memory and object management throughout agent lifecycle
+- **📚 Experience Learning** - Agents improve over time through memory-based reasoning
+- **🛠️ Dynamic Tool Creation** - Agents can generate and use custom tools on-demand
+- **🧠 Autonomous Reasoning** - Built-in cognitive capabilities for complex multi-step tasks
+- **⚙️ Config-Driven** - Easily modify behavior through configuration files
+
+## Installation
+
+This project uses [uv](https://docs.astral.sh/uv/) for fast, reliable package management.
+
+### Install uv
+
+```bash
+# macOS/Linux
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Or via pip
+pip install uv
+```
+
+See the [uv installation guide](https://docs.astral.sh/uv/getting-started/installation/) for more options.
+
+### Setup Environment
+
+```bash
+# Clone the repository
+git clone https://github.com/yourusername/agentz.git
+cd agentz
+
+# Sync dependencies
+uv sync
+```
+
+## Quick Start
+
+```python
+from pipelines.data_scientist import DataScientistPipeline
+
+pipe = DataScientistPipeline("pipelines/configs/data_science.yaml")
+
+pipe.run_sync()
+```
+
+## Building Your Own System
+
+### 1. Create a Custom Pipeline
+
+Inherit from `BasePipeline` to create your own agent workflow:
+
+```python
+from pipelines.base import BasePipeline
+
+
+class MyCustomPipeline(BasePipeline):
+    DEFAULT_CONFIG_PATH = "pipelines/configs/my_pipeline.yaml"
+
+    def __init__(self, config=None):
+        super().__init__(config)
+        # Add your custom initialization
+
+    async def run(self):
+        # Implement your workflow logic
+        pass
+```
+
+### 2. Add Custom Agents
+
+Implement your agents following the standard interface:
+
+```python
+from agents import Agent
+
+def create_my_agent(config):
+    return Agent(
+        name="my_agent",
+        instructions="Your agent instructions here",
+        model=config.main_model
+    )
+```
+
+### 3. Configure & Run
+
+Create a config file and run your pipeline:
+
+```python
+pipe = MyCustomPipeline(
+    data_path="your_data.csv",
+    user_prompt="Your task description",
+    provider="gemini",
+    model="gemini-2.5-flash"
+)
+
+pipe.run_sync()
+```
+
+## Architecture
+
+AgentZ is organised around a **central conversation state** and a set of declarative
+flow specifications that describe how agents collaborate. The main
+components you will interact with are:
+
+- **`pipelines/`** – High level orchestration that wires agents together.
+- **`agentz/agents/`** – Capability definitions for manager agents and tool agents.
+- **`agentz/flow/`** – Flow primitives (`FlowRunner`, `FlowNode`, `IterationFlow`) that
+  execute declarative pipelines.
+- **`agentz/memory/`** – Structured state management (`ConversationState`,
+  `ToolExecutionResult`, global memory helpers).
+- **`examples/`** – Example scripts showing end-to-end usage.
+
+```
+agentz/
+├── pipelines/
+│   ├── base.py               # Base pipeline with config management & helpers
+│   ├── flow_runner.py        # Declarative flow executor utilities
+│   └── data_scientist.py     # Reference research pipeline
+├── agentz/
+│   ├── agents/
+│   │   ├── manager_agents/   # Observe, evaluate, routing, writer agents
+│   │   └── tool_agents/      # Specialised tool executors
+│   ├── flow/                 # Flow node definitions and runtime objects
+│   ├── memory/               # Conversation state & persistence utilities
+│   ├── llm/                  # LLM adapters and setup helpers
+│   └── tools/                # Built-in tools
+└── examples/
+    └── data_science.py       # Example workflows
+```
+
+### Declarative Pipeline Flow
+
+The reference `DataScientistPipeline` models an entire research workflow using
+three building blocks:
+
+1. **Central ConversationState** – A shared store that captures every field any
+   agent might read or write (iteration metadata, gaps, observations, tool
+   results, timing, final report, etc.). Each loop creates a new
+   `IterationRecord`, enabling partial updates and clean tracking of tool
+   outcomes.
+2. **Structured IO Contracts** – Each agent step declares the Pydantic model it
+   expects and produces (for example `KnowledgeGapOutput` or
+   `AgentSelectionPlan`). Input builders map slices of `ConversationState` into
+   those models and output handlers merge the validated results back into the
+   central state.
+3. **Declarative FlowRunner** – The pipeline defines an `IterationFlow` of
+   `FlowNode`s such as observe → evaluate → route → tools. Loop and termination
+   logic are expressed with predicates (`loop_condition`, `condition`), so the
+   executor can stop when evaluation marks `state.complete` or constraints are
+   reached. Finalisation steps (like the writer agent) run after the iteration
+   loop using the same structured IO.
+
+Because the flow is declarative and all state is centralised, extending the
+pipeline is as simple as adding a new node, output field, or tool capability—no
+custom `run()` logic is required beyond sequencing the flow runner.
+
+## Benchmarks
+
+AgentZ has been verified on several benchmarks for multi-agent research:
+
+- **Data Science Tasks**: State-of-the-art performance on automated ML pipelines
+- **Complex Reasoning**: Competitive results on multi-step reasoning benchmarks
+- **Tool Usage**: High accuracy in dynamic tool selection and execution
+
+*Detailed benchmark results and comparisons coming soon.*
+
+## Roadmap
+
+- [x] Persistence Process - Stateful agent workflows
+- [x] Experience Learning - Memory-based reasoning
+- [x] Tool Design - Dynamic tool creation
+- [ ] Workflow RAG - Retrieval-augmented generation for complex workflows
+- [ ] MCPs - Model Context Protocol support for enhanced agent communication
+
+## Key Design Principles
+
+1. **Minimal Core** - Keep the base system simple and extensible
+2. **Intelligent Defaults** - Provide strong baseline implementations
+3. **Research-First** - Design for experimentation and comparison
+4. **Modular Architecture** - Easy to swap components and test variations
+5. **Production-Ready** - Scale from research prototypes to deployed systems
+
+## Use Cases
+
+- **Multi-Agent Research** - Baseline for comparing agent architectures
+- **Automated Data Science** - End-to-end ML pipeline automation
+- **Complex Task Decomposition** - Break down and solve multi-step problems
+- **Tool-Using Agents** - Research on dynamic tool creation and usage
+- **Agent Memory Systems** - Study persistence and experience learning
+
+## Citation
+
+If you use AgentZ in your research, please cite:
+
+```bibtex
+@software{agentz2025,
+  title={AgentZ: A Research-Oriented Multi-Agent System Platform},
+  author={Your Name},
+  year={2025},
+  url={https://github.com/yourusername/agentz}
+}
+```
+
+## Contributing
+
+We welcome contributions! AgentZ is designed to be a community resource for multi-agent research. Please open an issue or submit a pull request.
+
+## License
+
+[Your License Here]
+
+## Acknowledgements
+
+AgentZ is built with inspiration from the multi-agent systems research community. We thank the developers of various LLM frameworks and tools that make this work possible.
+
+---
+
+<div align="center">
+
+**AgentZ**: Building intelligent agents from zero to hero 🚀
+
+</div>