waccy 0.0a1__tar.gz

waccy-0.0a1/.gitignore

@@ -0,0 +1,129 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/

waccy-0.0a1/CODE_OF_CONDUCT.md

@@ -0,0 +1,93 @@
+
+# WACCY Code of Conduct
+
+Adapted from Contributor Covenant 3.0 Code of Conduct
+
+## Our Pledge
+
+We pledge to make our community welcoming, safe, and equitable for all.
+
+We are committed to fostering an environment that respects and promotes the dignity, rights, and contributions of all individuals, regardless of characteristics including race, ethnicity, caste, color, age, physical characteristics, neurodiversity, disability, sex or gender, gender identity or expression, sexual orientation, language, philosophy or religion, national or social origin, socio-economic position, level of education, or other status. The same privileges of participation are extended to everyone who participates in good faith and in accordance with this Covenant.
+
+
+## Encouraged Behaviors
+
+While acknowledging differences in social norms, we all strive to meet our community's expectations for positive behavior. We also understand that our words and actions may be interpreted differently than we intend based on culture, background, or native language.
+
+With these considerations in mind, we agree to behave mindfully toward each other and act in ways that center our shared values, including:
+
+1. Respecting the **purpose of our community**, our activities, and our ways of gathering.
+2. Engaging **kindly and honestly** with others.
+3. Respecting **different viewpoints** and experiences.
+4. **Taking responsibility** for our actions and contributions.
+5. Gracefully giving and accepting **constructive feedback**.
+6. Committing to **repairing harm** when it occurs.
+7. Behaving in other ways that promote and sustain the **well-being of our community**.
+
+
+## Restricted Behaviors
+
+We agree to restrict the following behaviors in our community. Instances, threats, and promotion of these behaviors are violations of this Code of Conduct.
+
+1. **Harassment.** Violating explicitly expressed boundaries or engaging in unnecessary personal attention after any clear request to stop.
+2. **Character attacks.** Making insulting, demeaning, or pejorative comments directed at a community member or group of people.
+3. **Stereotyping or discrimination.** Characterizing anyone’s personality or behavior on the basis of immutable identities or traits.
+4. **Sexualization.** Behaving in a way that would generally be considered inappropriately intimate in the context or purpose of the community.
+5. **Violating confidentiality**. Sharing or acting on someone's personal or private information without their permission.
+6. **Endangerment.** Causing, encouraging, or threatening violence or other harm toward any person or group.
+7. Behaving in other ways that **threaten the well-being** of our community.
+
+### Other Restrictions
+
+1. **Misleading identity.** Impersonating someone else for any reason, or pretending to be someone else to evade enforcement actions.
+2. **Failing to credit sources.** Not properly crediting the sources of content you contribute.
+3. **Promotional materials**. Sharing marketing or other commercial content in a way that is outside the norms of the community.
+4. **Irresponsible communication.** Failing to responsibly present content which includes, links or describes any other restricted behaviors.
+
+
+## Reporting an Issue
+
+Tensions can occur between community members even when they are trying their best to collaborate. Not every conflict represents a code of conduct violation, and this Code of Conduct reinforces encouraged behaviors and norms that can help avoid conflicts and minimize harm.
+
+When an incident does occur, it is important to report it promptly. To report a possible violation, please use the contact methods available on the project's GitHub repository.
+
+Community Moderators take reports of violations seriously and will make every effort to respond in a timely manner. They will investigate all reports of code of conduct violations, reviewing messages, logs, and recordings, or interviewing witnesses and other participants. Community Moderators will keep investigation and enforcement actions as transparent as possible while prioritizing safety and confidentiality. In order to honor these values, enforcement actions are carried out in private with the involved parties, but communicating to the whole community may be part of a mutually agreed upon resolution.
+
+
+## Addressing and Repairing Harm
+
+If an investigation by the Community Moderators finds that this Code of Conduct has been violated, the following enforcement ladder may be used to determine how best to repair harm, based on the incident's impact on the individuals involved and the community as a whole. Depending on the severity of a violation, lower rungs on the ladder may be skipped.
+
+1) Warning
+   1) Event: A violation involving a single incident or series of incidents.
+   2) Consequence: A private, written warning from the Community Moderators.
+   3) Repair: Examples of repair include a private written apology, acknowledgement of responsibility, and seeking clarification on expectations.
+2) Temporarily Limited Activities
+   1) Event: A repeated incidence of a violation that previously resulted in a warning, or the first incidence of a more serious violation.
+   2) Consequence: A private, written warning with a time-limited cooldown period designed to underscore the seriousness of the situation and give the community members involved time to process the incident. The cooldown period may be limited to particular communication channels or interactions with particular community members.
+   3) Repair: Examples of repair may include making an apology, using the cooldown period to reflect on actions and impact, and being thoughtful about re-entering community spaces after the period is over.
+3) Temporary Suspension
+   1) Event: A pattern of repeated violation which the Community Moderators have tried to address with warnings, or a single serious violation.
+   2) Consequence: A private written warning with conditions for return from suspension. In general, temporary suspensions give the person being suspended time to reflect upon their behavior and possible corrective actions.
+   3) Repair: Examples of repair include respecting the spirit of the suspension, meeting the specified conditions for return, and being thoughtful about how to reintegrate with the community when the suspension is lifted.
+4) Permanent Ban
+   1) Event: A pattern of repeated code of conduct violations that other steps on the ladder have failed to resolve, or a violation so serious that the Community Moderators determine there is no way to keep the community safe with this person as a member.
+   2) Consequence: Access to all community spaces, tools, and communication channels is removed. In general, permanent bans should be rarely used, should have strong reasoning behind them, and should only be resorted to if working through other remedies has failed to change the behavior.
+   3) Repair: There is no possible repair in cases of this severity.
+
+This enforcement ladder is intended as a guideline. It does not limit the ability of Community Managers to use their discretion and judgment, in keeping with the best interests of our community.
+
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public or other spaces. Examples of representing our community include using an official email address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
+
+
+## Attribution
+
+This Code of Conduct is adapted from the Contributor Covenant, version 3.0, permanently available at [https://www.contributor-covenant.org/version/3/0/](https://www.contributor-covenant.org/version/3/0/).
+
+Contributor Covenant is stewarded by the Organization for Ethical Source and licensed under CC BY-SA 4.0. To view a copy of this license, visit [https://creativecommons.org/licenses/by-sa/4.0/](https://creativecommons.org/licenses/by-sa/4.0/)
+
+For answers to common questions about Contributor Covenant, see the FAQ at [https://www.contributor-covenant.org/faq](https://www.contributor-covenant.org/faq). Translations are provided at [https://www.contributor-covenant.org/translations](https://www.contributor-covenant.org/translations). Additional enforcement and community guideline resources can be found at [https://www.contributor-covenant.org/resources](https://www.contributor-covenant.org/resources). The enforcement ladder was inspired by the work of [Mozilla’s code of conduct team](https://github.com/mozilla/inclusion).
+

waccy-0.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 David Spencer
+
+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.

waccy-0.0a1/PKG-INFO

@@ -0,0 +1,442 @@
+Metadata-Version: 2.4
+Name: waccy
+Version: 0.0a1
+Summary: Intelligent financial modeling platform for small businesses
+Project-URL: Homepage, https://github.com/DecisionNerd/waccy
+Project-URL: Repository, https://github.com/DecisionNerd/waccy
+Project-URL: Issues, https://github.com/DecisionNerd/waccy/issues
+Project-URL: Documentation, https://github.com/DecisionNerd/waccy#readme
+Author: WACCY Contributors
+License: MIT
+License-File: LICENSE
+Keywords: accounting,finance,financial-modeling,valuation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial
+Requires-Python: >=3.13
+Requires-Dist: numpy>=2.3.5
+Requires-Dist: pandera>=0.27.0
+Requires-Dist: polars>=1.36.1
+Requires-Dist: pydantic>=2.12.5
+Provides-Extra: edgar
+Requires-Dist: waccy-edgar>=0.1.0; extra == 'edgar'
+Provides-Extra: quickbooks
+Requires-Dist: waccy-quickbooks>=0.1.0; extra == 'quickbooks'
+Description-Content-Type: text/markdown
+
+# WACCY
+
+**Intelligent Financial Modeling Platform for Small Businesses**
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
+[![Code style: ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+
+<div align="center">
+  <img src="waccy-logo-NoBG.png" alt="WACCY Logo" width="400"/>
+</div>
+
+WACCY is an intelligent financial modeling platform designed to automatically extract, parse, classify, and synthesize business data from diverse sources to generate sophisticated, production-grade financial models and operating analyses. **The platform's primary focus is on small businesses—from sole proprietorships to growing companies—that struggle with messy, incomplete, and poorly-maintained financial records.**
+
+Unlike large enterprises with dedicated accounting teams, small businesses often have inconsistent record-keeping, ambiguous account classifications, incomplete data, and limited financial infrastructure. WACCY transforms this raw, often chaotic business data into comprehensive, auditable, and decision-ready financial models that adhere to institutional-quality standards.
+
+## 🚀 Quick Start
+
+### Installation
+
+WACCY uses `uv`, the modern Python package manager. Install the core platform:
+
+```bash
+# Install uv if you haven't already
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Install WACCY core platform
+uv pip install waccy
+
+# Install with core extensions (QuickBooks Online and SEC EDGAR)
+uv pip install "waccy[quickbooks,edgar]"
+
+# Or install individual extensions
+uv pip install waccy-quickbooks
+uv pip install waccy-edgar
+```
+
+### Basic Usage
+
+```python
+from waccy.extraction import ExtractorRegistry
+from waccy.modeling import ModelBuilder
+
+# Discover available extractors
+registry = ExtractorRegistry()
+available_sources = registry.list_extractors()
+print(f"Available data sources: {available_sources}")
+
+# Extract data from QuickBooks Online
+quickbooks_extractor = registry.get_extractor("quickbooks")
+extracted_data = quickbooks_extractor().extract({
+    "company_id": "your_company_id",
+    "date_range": ("2023-01-01", "2024-12-31")
+})
+
+# Build a 3-statement financial model
+builder = ModelBuilder()
+model = builder.build_three_statement_model(
+    extracted_data=extracted_data,
+    forecast_periods=12
+)
+
+# Export to Google Sheets
+builder.export_to_sheets(model, output_path="financial_model.xlsx")
+```
+
+## 📋 Core Features
+
+### 🤖 **AI-Powered Data Extraction & Classification**
+
+* **Intelligent Account Mapping**: LLM-enhanced classification for ambiguous account names and inconsistent categorizations
+* **Missing Data Inference**: Patterns learned from high-quality sources (EDGAR filings) to infer missing information
+* **Causal Chain Recognition**: Understands how financial events cascade through statements
+* **Terminology Normalization**: Maps equivalent concepts across different naming conventions
+* **Confidence Scoring**: Every classification includes a confidence score for quality assessment
+
+### 🏗️ **Standardized Financial Ontology**
+
+* **WACCY Standard Chart of Accounts**: Comprehensive, standardized classification ontology
+* **Universal Mapping**: All data sources map to the same standard accounts for consistency
+* **Industry Templates**: Pre-configured extensions for SaaS, manufacturing, retail, real estate, and more
+* **Quality Quantification**: Standardized ontology enables measurement of data quality and model reliability
+
+### 📊 **Institutional-Quality Financial Models**
+
+* **3-Statement Integrated Models**: Income statement, balance sheet, and cash flow with full balancing
+* **DCF Valuation Models**: Detailed free cash flow construction, terminal value analysis, WACC calculation
+* **Trading Comparables**: Peer company analysis with multiple calculation and benchmarking
+* **Transaction Comparables**: Precedent M&A transaction analysis
+* **LBO Models**: Leveraged buyout analysis with returns calculation and debt schedules
+* **M&A Models**: Accretion/dilution analysis with purchase accounting
+* **Specialized Models**: SaaS cohort models, REIT models, project finance, cap tables, and more
+
+### 🔌 **Modular Extension Architecture**
+
+* **Core Platform**: Focused core with QuickBooks Online and SEC EDGAR as primary data sources
+* **Extensible Design**: Community-developed extension packages for additional data sources
+* **Entry Point Discovery**: Automatic discovery of extensions via Python entry points
+* **Simple Installation**: Install only the extensions you need
+
+### 📈 **Advanced Forecasting & Analysis**
+
+* **Driver-Based Forecasting**: Revenue builds from price × volume, units × ARPU, cohort models
+* **Working Capital Modeling**: DSO, DIO, DPO analysis with seasonality adjustments
+* **Debt & Interest Modeling**: Revolver mechanics, amortization schedules, cash sweep waterfalls
+* **Tax Modeling**: Effective tax rates, DTAs/DTLs, NOL utilization tracking
+* **Sensitivity Analysis**: Comprehensive scenario modeling and tornado charts
+
+### ✅ **Data Quality & Validation**
+
+* **Pandera Validation**: Schema-based validation for extracted data
+* **Mapping Confidence Scores**: Quantify the reliability of account mappings
+* **Reconciliation Checks**: Cross-referencing between sources and balance checks
+* **Audit Trails**: Every data point traceable to source with full provenance
+
+### 📝 **Professional Model Outputs**
+
+* **Google Sheets Export**: Production-ready spreadsheet models with proper formatting
+* **Professional Architecture**: Modular tab structures, consistent time axis, clear sign conventions
+* **Color Conventions**: Inputs in blue, calculations in black, outputs in green
+* **Balance Checks**: Built-in reconciliation tables and error flags
+* **Scenario Tooling**: Data tables for sensitivity analysis, scenario toggles, goal seek integration
+
+## 🔄 Complete Workflow
+
+```python
+from waccy.extraction import ExtractorRegistry
+from waccy.classification import ClassificationEngine
+from waccy.modeling import ModelBuilder
+from waccy.core.ontology import StandardChartOfAccounts
+
+# 1. Extract data from QuickBooks Online (handles messy, incomplete records)
+registry = ExtractorRegistry()
+extractor = registry.get_extractor("quickbooks")()
+credentials = {
+    "client_id": "your_client_id",
+    "client_secret": "your_client_secret",
+    "access_token": "your_access_token"
+}
+extractor.authenticate(credentials)
+
+extracted_data = extractor.extract({
+    "company_id": "123456789",
+    "date_range": ("2022-01-01", "2024-12-31"),
+    "include_transactions": True
+})
+
+# 2. Classify and map to standard accounts (with LLM enhancement for ambiguity)
+ontology = StandardChartOfAccounts()
+classification_engine = ClassificationEngine()
+
+for account in extracted_data.accounts:
+    mapped_account, confidence = classification_engine.classify_account(
+        source_account_name=account.name,
+        transaction_patterns=account.transaction_history,
+        context={"company_type": "SaaS", "industry": "Software"}
+    )
+    print(f"Mapped '{account.name}' to '{mapped_account.name}' (confidence: {confidence:.2f})")
+
+# 3. Build 3-statement integrated model
+builder = ModelBuilder()
+model = builder.build_three_statement_model(
+    extracted_data=extracted_data,
+    forecast_periods=24
+)
+
+# 4. Generate DCF valuation
+dcf_model = builder.build_dcf_model(
+    three_statement_model=model,
+    wacc=0.10,
+    terminal_growth_rate=0.03,
+    exit_multiple=12.0
+)
+
+# 5. Export to Google Sheets
+builder.export_to_sheets(model, output_path="financial_model.xlsx")
+builder.export_to_sheets(dcf_model, output_path="dcf_valuation.xlsx")
+
+# 6. Generate quality report
+quality_report = extracted_data.generate_quality_report()
+print(f"Data completeness: {quality_report.completeness:.2%}")
+print(f"Average mapping confidence: {quality_report.avg_confidence:.2f}")
+print(f"Issues flagged: {len(quality_report.issues)}")
+```
+
+## 📊 Example Output
+
+### Standardized Account Mapping
+
+**Source Account**: `"Sales Revenue"` (QuickBooks)  
+**Mapped To**: `Revenue - Product Sales` (WACCY Standard)  
+**Confidence**: 0.95  
+**Validation**: ✅ Transaction patterns match revenue recognition
+
+### 3-Statement Model Structure
+
+```
+Financial Model.xlsx
+├── Assumptions
+│   ├── Revenue Drivers
+│   ├── Cost Assumptions
+│   └── Working Capital
+├── Income Statement
+│   ├── Historical (3 years)
+│   └── Forecast (2 years)
+├── Balance Sheet
+│   ├── Assets (Current & Non-Current)
+│   ├── Liabilities (Current & Non-Current)
+│   └── Equity
+├── Cash Flow Statement
+│   ├── Operating Activities
+│   ├── Investing Activities
+│   └── Financing Activities
+├── Supporting Schedules
+│   ├── Working Capital Detail
+│   ├── Debt Schedule
+│   └── Depreciation
+└── Checks & Reconciliations
+    ├── Balance Checks
+    └── Quality Metrics
+```
+
+## 🔗 Core Data Sources
+
+### QuickBooks Online (QBO)
+
+**Primary Data Source** - The accounting system most commonly used by small businesses.
+
+* Direct API integration for chart of accounts, general ledger, and financial statements
+* Intelligent handling of ambiguous, inconsistently-named accounts
+* Transaction-level detail extraction
+* Vendor and customer data integration
+* Skeptical treatment of source classifications with validation
+
+### SEC EDGAR
+
+**Pattern Learning & Reference Data** - High-quality financial data for learning and benchmarking.
+
+* Automated parsing of 10-K, 10-Q, 8-K filings
+* Proxy statement and registration statement processing
+* Pattern extraction for proper financial classification
+* Learning causal chains from professional financial reports
+* Application of learned patterns to small business data
+
+### Extension Packages
+
+Additional data sources available as modular extensions:
+
+* `waccy-google` - Google Drive and Gmail integration
+* `waccy-xero` - Xero accounting system
+* `waccy-sage` - Sage accounting platform
+* `waccy-stripe` - Payment processor data
+* `waccy-salesforce` - CRM and sales pipeline data
+
+## 📁 Project Structure
+
+```
+waccy/
+├── src/
+│   └── waccy/
+│       ├── core/
+│       │   ├── ontology.py          # Standardized chart of accounts
+│       │   ├── models.py            # Core data models (Pydantic)
+│       │   └── validation.py        # Data validation (Pandera)
+│       ├── extraction/
+│       │   ├── base.py              # Abstract base classes
+│       │   ├── registry.py          # Extension registry
+│       │   └── mapper.py            # Mapping to standard ontology
+│       ├── classification/
+│       │   ├── engine.py            # LLM-enhanced classification
+│       │   ├── patterns.py          # Pattern matching from EDGAR
+│       │   └── confidence.py        # Confidence scoring
+│       ├── modeling/
+│       │   ├── builder.py           # Model construction
+│       │   ├── templates.py         # Model templates
+│       │   └── exporters.py         # Google Sheets export
+│       └── utils/
+│           ├── dates.py
+│           ├── formatting.py
+│           └── validation.py
+├── tests/
+│   ├── unit/
+│   ├── integration/
+│   └── fixtures/
+├── docs/
+│   ├── 0-MISSION.md
+│   ├── 1-ARCHITECTURE.md
+│   ├── 2-EXPERIENCE.md
+│   └── skills_models.md
+└── pyproject.toml
+```
+
+## 🧪 Testing
+
+```bash
+# Install development dependencies
+uv sync --dev
+
+# Run all tests
+uv run pytest
+
+# Run with coverage
+uv run pytest --cov=waccy --cov-report=html
+
+# Run specific test suites
+uv run pytest tests/unit/
+uv run pytest tests/integration/
+
+# Format and lint with ruff
+uv run ruff format
+uv run ruff check --fix
+
+# Type checking with mypy
+uv run mypy src/waccy
+```
+
+## 📚 Documentation
+
+* **[Mission Statement](docs/0-MISSION.md)** - Project goals, philosophy, and roadmap
+* **[Architecture](docs/1-ARCHITECTURE.md)** - Technical architecture and design principles
+* **[Experience Guide](docs/2-EXPERIENCE.md)** - User experience and workflows
+* **[Skills & Models](docs/skills_models.md)** - Financial modeling capabilities
+
+## 🏛️ Design Principles
+
+1. **Simplicity and Focus**: Core platform maintains a simple, focused design with essential data sources (QBO and EDGAR)
+
+2. **Standardized Ontology First**: All financial data maps to a standardized WACCY chart of accounts, ensuring consistency and comparability
+
+3. **Modular Extensibility**: New data sources and model types added as separate packages that conform to core interfaces
+
+4. **Accuracy First**: Deterministic functions preferred over probabilistic models. LLMs used for parsing and classification, not financial calculations
+
+5. **Transparency and Auditability**: Every data point traceable to source, every calculation explainable, every assumption documented
+
+6. **Professional Standards**: Models adhere to institutional-quality standards for architecture, formatting, and presentation
+
+7. **Quality Quantification**: Standardized ontology enables measurement and reporting of data quality and model output reliability
+
+8. **Small Business Focus**: Designed primarily for small businesses—from sole proprietorships to growing companies—handling messy, incomplete data
+
+## 🤝 Contributing
+
+We welcome contributions! WACCY is built for the small business community, and we'd love your help making financial modeling more accessible.
+
+### Getting Started
+
+1. **Fork the repository** on GitHub
+2. **Create a feature branch** for your contribution
+3. **Set up development environment**:
+   ```bash
+   git clone https://github.com/your-username/waccy.git
+   cd waccy
+   uv sync --dev
+   ```
+4. **Make your changes** following our coding standards:
+   - Use `ruff` for formatting and linting
+   - Add type hints with `mypy` compliance
+   - Write tests for new functionality
+   - Update documentation as needed
+5. **Run tests and linting**:
+   ```bash
+   uv run pytest
+   uv run ruff check
+   uv run mypy src/
+   ```
+6. **Submit a pull request** with a clear description of your changes
+
+### Creating Extensions
+
+Want to add a new data source? Create an extension package:
+
+1. Create a new package: `waccy-yourdatasource`
+2. Implement the `Extractor` interface from `waccy.extraction.base`
+3. Register your extension via entry points
+4. Follow the [Extension Development Guide](docs/1-ARCHITECTURE.md#extension-development-guide)
+
+See our [Architecture Documentation](docs/1-ARCHITECTURE.md) for detailed extension development guidelines.
+
+### Code of Conduct
+
+Please read and follow our [Code of Conduct](CODE_OF_CONDUCT.md) to ensure a welcoming environment for all contributors.
+
+## 📈 Project Status
+
+* **Phase 1**: 📋 Planned - Core foundation and 3-statement models
+* **Phase 2**: 📋 Planned - Public market data and pattern learning (EDGAR)
+* **Phase 3**: 📋 Planned - Advanced valuation models (DCF, M&A, LBO)
+* **Phase 4**: 📋 Planned - Specialized model types (SaaS, REIT, project finance)
+* **Phase 5**: 📋 Planned - Advanced analysis and decision support
+
+**Current Status**: Early development - Architecture and core platform design  
+**Python Version**: 3.13+  
+**Package Manager**: [uv](https://github.com/astral-sh/uv)  
+**CI/CD**: GitHub Actions (coming soon)
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🙏 Acknowledgments
+
+* **Small Business Community** - Built for entrepreneurs and small business owners who need professional financial modeling
+* **Financial Modeling Community** - Inspired by institutional-quality modeling standards
+* **Open Source Tools**: 
+  * [uv](https://github.com/astral-sh/uv) - Modern Python package manager
+  * [ruff](https://github.com/astral-sh/ruff) - Fast Python linter and formatter
+  * [Pydantic](https://github.com/pydantic/pydantic) - Data validation framework
+  * [Polars](https://github.com/pola-rs/polars) - High-performance data manipulation
+  * [Pandera](https://github.com/pandera-dev/pandera) - Statistical data validation
+
+---
+
+**Made with 🤪 for small businesses that deserve institutional-quality financial modeling**