windyboy
f7e54692a9
- Add core agent architecture with Command + Skill pattern - Implement Claude API integration for content analysis - Add Obsidian REST API integration for vault operations - Create conversational interface (v2.0) with natural language processing - Add comprehensive configuration management and validation - Include project documentation and developer guides - Set up testing framework with unit, integration, and property tests - Add Kiro specs for Claude API configuration and code quality improvements - Configure project steering files for development guidelines
141 lines
5.1 KiB
Markdown
141 lines
5.1 KiB
Markdown
# Project Structure
|
|
|
|
## Directory Organization
|
|
|
|
```
|
|
journal_organizer/
|
|
├── __init__.py # Package initialization
|
|
├── __main__.py # Entry point for python -m execution
|
|
├── main.py # v1.0 CLI entry and Agent initialization
|
|
├── chat_main.py # v2.0 conversational interface entry
|
|
├── agent_core.py # Core Agent framework (Command + Skill)
|
|
├── config.py # Configuration management utilities
|
|
├── server.py # Optional server interface
|
|
├── config.example.yaml # Configuration template
|
|
├── requirements.txt # Python dependencies
|
|
├── README.md # v1.0 documentation
|
|
├── README_V2.md # v2.0 documentation
|
|
├── DEVELOPER_GUIDE.md # Development guidelines
|
|
├── OBSIDIAN_INTEGRATION.md # Obsidian integration guide
|
|
├── commands/ # Command implementations
|
|
│ ├── __init__.py
|
|
│ └── organize_command.py # Main journal organization command
|
|
├── skills/ # Skill implementations
|
|
│ ├── __init__.py
|
|
│ ├── obsidian_skill.py # Obsidian API integration skills
|
|
│ └── claude_skill.py # Claude AI integration skills
|
|
└── conversation/ # v2.0 conversational layer
|
|
├── __init__.py
|
|
├── conversational_agent.py # Main conversational agent
|
|
├── conversation_state.py # State management
|
|
├── intent_understanding.py # Natural language understanding
|
|
└── response_generator.py # Response generation
|
|
```
|
|
|
|
## Core Components
|
|
|
|
### Agent Core (`agent_core.py`)
|
|
- **Agent**: Main orchestrator class
|
|
- **Command**: Abstract base for high-level operations
|
|
- **Skill**: Abstract base for atomic operations
|
|
- **SkillChain**: Sequential skill execution
|
|
- **SkillResult**: Standardized result format
|
|
- **CommandContext**: Execution context container
|
|
|
|
### Entry Points
|
|
- **`__main__.py`**: Package entry point (`python -m journal_organizer`)
|
|
- **`main.py`**: v1.0 CLI with argparse-based command handling
|
|
- **`chat_main.py`**: v2.0 conversational interface with natural language processing
|
|
|
|
### Command Layer (`commands/`)
|
|
Commands orchestrate multiple Skills to accomplish complex tasks:
|
|
- **OrganizeCommand**: Main journal analysis and organization workflow
|
|
- Commands inherit from `Command` base class
|
|
- Commands register and coordinate Skills
|
|
- Commands handle parameter validation and error recovery
|
|
|
|
### Skill Layer (`skills/`)
|
|
Skills perform atomic operations:
|
|
- **ObsidianReadSkill**: Read notes from Obsidian vault
|
|
- **ObsidianWriteSkill**: Create/update notes in Obsidian
|
|
- **ObsidianAppendSkill**: Append content to existing notes
|
|
- **ObsidianListFilesSkill**: List files in vault directories
|
|
- **ClaudeAnalyzeSkill**: Analyze journal content with Claude
|
|
- **ClaudeTransformSkill**: Transform content formats with Claude
|
|
|
|
### Conversational Layer (`conversation/`)
|
|
v2.0 natural language interface:
|
|
- **ConversationalAgent**: Main conversation coordinator
|
|
- **IntentUnderstanding**: Maps natural language to commands/parameters
|
|
- **ConversationState**: Manages chat history and context
|
|
- **ResponseGenerator**: Generates natural language responses
|
|
|
|
## Naming Conventions
|
|
|
|
### Files and Modules
|
|
- Snake_case for Python files: `organize_command.py`
|
|
- Package names match directory structure
|
|
- Skills end with `_skill.py`
|
|
- Commands end with `_command.py`
|
|
|
|
### Classes
|
|
- PascalCase for class names: `OrganizeCommand`, `ClaudeAnalyzeSkill`
|
|
- Skills inherit from `Skill` base class
|
|
- Commands inherit from `Command` base class
|
|
- Result objects use `Result` suffix: `SkillResult`
|
|
|
|
### Methods and Variables
|
|
- Snake_case for methods and variables: `execute_command`, `api_key`
|
|
- Async methods use `async def` prefix
|
|
- Private methods start with underscore: `_parse_response`
|
|
|
|
### Constants and Enums
|
|
- UPPER_CASE for constants: `MAX_RETRIES`
|
|
- PascalCase for Enums: `SkillType`, `TaskStatus`
|
|
|
|
## Configuration Structure
|
|
|
|
### YAML Configuration (`config.yaml`)
|
|
```yaml
|
|
obsidian:
|
|
vault_path: "/path/to/vault"
|
|
rest_api:
|
|
url: "https://localhost:27123"
|
|
api_key: "your-key"
|
|
verify_ssl: false
|
|
|
|
claude:
|
|
api_key: "${ANTHROPIC_API_KEY}"
|
|
model: "claude-3-5-sonnet-20241022"
|
|
max_tokens: 4096
|
|
|
|
journal:
|
|
daily_notes_folder: "Daily"
|
|
date_format: "YYYY-MM-DD"
|
|
|
|
output:
|
|
experiences_folder: "Knowledge/Experiences"
|
|
lessons_folder: "Knowledge/Lessons"
|
|
# ... other output folders
|
|
```
|
|
|
|
## Extension Patterns
|
|
|
|
### Adding New Skills
|
|
1. Create new file in `skills/` directory
|
|
2. Inherit from `Skill` base class
|
|
3. Implement `execute()` method returning `SkillResult`
|
|
4. Register skill in relevant commands
|
|
|
|
### Adding New Commands
|
|
1. Create new file in `commands/` directory
|
|
2. Inherit from `Command` base class
|
|
3. Register required skills in `__init__()`
|
|
4. Implement `execute()` method with skill orchestration
|
|
5. Register command in `main.py` or `chat_main.py`
|
|
|
|
### Extending Conversational Capabilities
|
|
1. Add new intent patterns in `intent_understanding.py`
|
|
2. Update command keyword mappings
|
|
3. Extend parameter extraction patterns
|
|
4. Add response templates in `response_generator.py` |